Astro "Cannot find package 'astro'" in CI

By Daniel Zoghalchali·Latchkey

Running Astro requires the astro package present in node_modules on the runner. This error means the install did not put it there: dependencies were skipped, a cache restored a partial tree, or the wrong lockfile was used.

What this error means

A build or astro command fails with "Cannot find package 'astro'" or "astro: command not found", even though it works locally.

node:internal/modules/esm/resolve:264
Error: Cannot find package 'astro' imported from /home/runner/work/site/astro.config.mjs

Common causes

Dependencies not installed on the runner

CI skipped the install step, ran --production where astro is a devDependency, or restored a cache without a real install.

A cache masking a missing package

A restored node_modules cache is stale or partial, so astro is absent while other packages are present.

How to fix it

Install with the lockfile before building

1. Add an explicit npm ci (or the equivalent for yarn/pnpm) before the build.
2. Ensure astro is a dependency or included in the install (do not drop dev packages the build needs).
3. Re-run the build after the install.

- run: npm ci
- run: npm run build

Cache the package manager store, not node_modules

Cache ~/.npm (or the pnpm/yarn store) keyed on the lockfile and still run a real install, so the tree is always complete.

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'

How to prevent it

• Always run a real install (npm ci) in CI.
• Cache the package manager store, not node_modules directly.
• Do not use --production when the build needs devDependencies.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation