Astro "build failed" - Fix astro build Errors in CI

By Kaveh Alemi·Latchkey

Astro builds your site to static HTML by default, or to a server bundle when output: "server"/"hybrid" is set. The build fails when an SSR adapter is missing for server output, a framework integration is not installed, or a page throws while prerendering.

What this error means

astro build stops with a [build] error - commonly Cannot use output: 'server' without an adapter, an "Unknown file extension" for a framework component, or an exception thrown in a page during static generation.

[build] Cannot use `output: 'server'` without an adapter. Please install
and configure the appropriate server adapter for your final deployment.
  at validateConfig (astro/dist/core/config)

Common causes

Server output without an adapter

Setting output: "server" or "hybrid" requires an SSR adapter (@astrojs/node, @astrojs/vercel, etc.). Without one configured, the build cannot produce a server bundle.

Framework integration not installed

Using React/Vue/Svelte components needs the matching @astrojs/* integration in astro.config. Missing it makes Astro unable to compile those components.

A page throws during prerender

A top-level await fetch or data access in a .astro page that fails at build time aborts static generation for that route.

How to fix it

Install and configure the adapter/integration

Add the adapter for server output, and the framework integration for UI components.

npm install @astrojs/node @astrojs/react
// astro.config.mjs
import node from '@astrojs/node'
import react from '@astrojs/react'
export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
  integrations: [react()],
})

Guard build-time data fetches

1. Wrap top-level fetches in pages and return a safe fallback or Astro.redirect on failure.
2. Provide build-time env vars the page reads in the CI build step.
3. Run astro build locally to reproduce the failing route.

How to prevent it

• Install an SSR adapter whenever output is server/hybrid.
• Add the @astrojs/* integration for each UI framework you use.
• Guard build-time fetches so a prerender error does not fail the whole build.

Frequently asked questions

Related guides

References

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