Astro shows “Legacy configuration detected” when astro.config.mjs contains an option from an older version that has since moved or been removed. The message names the key, for example “Legacy configuration detected:” followed by the option, and the hint says: “Please update your configuration to the new format.” It appears most often right after an upgrade, when experimental flags have become stable or an option has been renamed.
Key Takeaways
- The error names the exact key; search the upgrade guides for it.
- Experimental flags that became stable must be removed from
experimental, and sometimes moved to a top-level key.output: 'hybrid'no longer exists; use'static'with per-pageprerender = false.- Run
npx @astrojs/upgradeto update Astro and official integrations together.
Step 1: find the key
The error prints it. Open astro.config.mjs and locate it. If the config spreads in values from another file, search there too.
Step 2: look it up
Search the Astro upgrade guides for the key name; each major version’s guide lists removed and renamed options with before-and-after code. Common cases when upgrading older projects:
| Old | Now |
|---|---|
output: 'hybrid' |
output: 'static' (default) plus export const prerender = false on dynamic pages |
experimental.contentLayer |
Removed; the Content Layer is the default |
experimental.serverIslands |
Removed; server:defer works without a flag |
experimental.fonts |
Top-level fonts option |
experimental.responsiveImages |
Top-level image.layout and image.responsiveStyles |
| Integration-specific options | Check that integration’s changelog |
Always check the guide for your target version rather than relying on a table; options move between releases.
Step 3: update integrations too
Integrations have their own options that change between majors. Upgrade them together:
npx @astrojs/upgradeThis updates astro and the official @astrojs/* packages to compatible versions. Then rebuild and fix errors one at a time.
Step 4: let types help
Add the type comment at the top of your config so your editor flags unknown keys:
// @ts-check
import { defineConfig } from 'astro/config';
export default defineConfig({
// unknown or removed options are now underlined
});Other upgrade errors you may hit next
The Astro configuration docs show a theme’s config, and What is Astro? summarises what changed by Astro 7. The configuration reference lists every current option.
FAQ
Can I ignore the warning and keep the old key?
No. Legacy keys either do nothing or block the build. Move or remove them.
Where are the upgrade guides?
On docs.astro.build under Guides → Upgrade to, one guide per major version.