npm postinstall Blocked by Policy - Fix Native Setup Skipped in CI

By Daniel Zoghalchali·Latchkey

Some organizations enforce ignore-scripts=true globally for supply-chain safety. That is good policy, but packages that legitimately need postinstall (native builds, binary downloads) end up half-installed unless you rebuild them explicitly.

What this error means

Install succeeds with no error, but a dependency that relies on postinstall is missing its binary/native artifact and fails at runtime. Inspecting config shows a policy-set ignore-scripts=true (in a shared .npmrc or via an env var) that silently skipped the step.

Runtime output

# install completed; later at runtime:
Error: Cannot find module
'/app/node_modules/some-native/build/Release/addon.node'
# postinstall that builds addon.node never ran (ignore-scripts policy)

Diagnose it: reproduce the CI install locally

Install failures are usually environment drift rather than a broken lockfile: a different package-manager major, a different Node version, or a cache that is being restored from a run with different inputs. Reproduce the CI conditions before changing the lockfile, because regenerating it hides the real cause.

Terminal

# match the runner exactly, then install from a clean slate
node --version && npm --version
rm -rf node_modules
npm ci --foreground-scripts

# if that succeeds locally but fails in CI, the difference is the cache
# or the package-manager version, not your lockfile

Common causes

An org/global policy sets ignore-scripts

A shared/global .npmrc, a --ignore-scripts default, or npm_config_ignore_scripts=true in the environment disables all lifecycle scripts, including the ones some packages need.

The blocked package genuinely needs postinstall

Native-addon and binary-wrapping packages do their real install work in postinstall. With it blocked, the runtime files never materialize.

How to fix it

Rebuild the packages that need it

Keep the policy but explicitly rebuild the native packages after install.

Terminal

npm ci            # scripts blocked by policy
npm rebuild       # run install/build steps for native deps explicitly

Allow scripts narrowly where required

Audit which dependencies depend on postinstall before enforcing the policy.
For a trusted, lockfile-pinned set, scope the allowance to the install that needs it rather than disabling the policy globally.
Document why a given package needs its scripts so the exception is reviewable.

Verify the fix survives a cold cache

A green run immediately after a fix often proves nothing, because it restored a cache written before the change. Force a cold install once to confirm the fix is real.

.github/workflows/ci.yml

# temporarily bust the cache key to prove the fix on a cold runner
- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: npm
    cache-dependency-path: package-lock.json
# then bump this suffix once, run, and remove it
#   key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}-v2

How to prevent it

Pair an ignore-scripts policy with an explicit npm rebuild for natives.
Inventory postinstall-dependent packages up front.
Pin dependencies so allowing scripts stays auditable.

Frequently asked questions

What causes npm postinstall blocked by policy?

There are 2 common causes: an org/global policy sets ignore-scripts and the blocked package genuinely needs postinstall. A shared/global .npmrc, a --ignore-scripts default, or npm_config_ignore_scripts=true in the environment disables all lifecycle scripts, including the ones some packages need.

How do I fix npm postinstall blocked by policy?

There are 2 fixes depending on which cause you have: rebuild the packages that need it and allow scripts narrowly where required. Work through them in order, since the first is the most common.

What does npm postinstall blocked by policy actually mean?

Install succeeds with no error, but a dependency that relies on postinstall is missing its binary/native artifact and fails at runtime.

How do I stop npm postinstall blocked by policy happening again?

Pair an ignore-scripts policy with an explicit npm rebuild for natives. The prevention section lists 3 changes that keep it from recurring.