Astro integration "[astro] failed" (missing integration) in CI

By Daniel Zoghalchali·Latchkey

Astro loads integrations listed in astro.config at build start. If an integration package is referenced but not installed on the runner, the config fails to load and the build errors before compiling any page.

What this error means

The build fails at startup with a "Cannot find package '@astrojs/...'" or an "[astro] ... failed" message pointing at an integration in the config.

[astro] Cannot find package '@astrojs/mdx' imported from
/home/runner/work/site/astro.config.mjs
  Did you forget to install the integration? Run: npx astro add mdx

Common causes

The integration package is not installed

The config imports an integration, but the package was never added to dependencies or was dropped by a --production install.

A version mismatch with the Astro core

An integration built for a different major of Astro can fail to load against the installed core.

How to fix it

Add the integration properly

1. Run astro add <name> (or install the package) so it is in dependencies.
2. Commit the updated lockfile so CI installs it.
3. Re-run the build.

npx astro add mdx

Align integration and core versions

Match the integration major to the Astro core major, then reinstall.

npm install astro@latest @astrojs/mdx@latest

How to prevent it

• Add integrations with astro add so the dependency is recorded.
• Commit the lockfile after adding integrations.
• Keep integrations aligned with the Astro core major.

Frequently asked questions

Related guides

References

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