From fb7f1e4c7341e804aa6361c6ac3fe502348a35f5 Mon Sep 17 00:00:00 2001
From: Florian Lefebvre <contact@florian-lefebvre.dev>
Date: Thu, 20 Nov 2025 15:26:37 +0100
Subject: [PATCH 1/5] [next]: stabilize failOnPrerenderConflict

---
 astro.sidebar.ts                              |  1 -
 src/content/docs/en/guides/upgrade-to/v6.mdx  | 28 ++++++++++++--
 .../fail-on-prerender-conflict.mdx            | 37 -------------------
 .../fail-on-prerender-conflict.mdx            | 37 -------------------
 .../fail-on-prerender-conflict.mdx            | 37 -------------------
 5 files changed, 25 insertions(+), 115 deletions(-)
 delete mode 100644 src/content/docs/en/reference/experimental-flags/fail-on-prerender-conflict.mdx
 delete mode 100644 src/content/docs/fr/reference/experimental-flags/fail-on-prerender-conflict.mdx
 delete mode 100644 src/content/docs/ko/reference/experimental-flags/fail-on-prerender-conflict.mdx

diff --git a/astro.sidebar.ts b/astro.sidebar.ts
index 2b2b98ce93c1d..5e8d9be3f437f 100644
--- a/astro.sidebar.ts
+++ b/astro.sidebar.ts
@@ -148,7 +148,6 @@ export const sidebar = [
 					'reference/experimental-flags/client-prerender',
 					'reference/experimental-flags/content-intellisense',
 					'reference/experimental-flags/chrome-devtools-workspace',
-					'reference/experimental-flags/fail-on-prerender-conflict',
 				],
 			}),
 			'reference/legacy-flags',
diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx
index a96344079bc9d..0f8c6d78550e5 100644
--- a/src/content/docs/en/guides/upgrade-to/v6.mdx
+++ b/src/content/docs/en/guides/upgrade-to/v6.mdx
@@ -291,7 +291,6 @@ const { Content, headings } = await render(post);
 
 <ReadMore> See [the Astro v5 upgrade guide](/en/guides/upgrade-to/v5/#legacy-v20-content-collections-api) for previous guidance about backwards compatibility of legacy collections in Astro v5 and full step-by-step instructions for upgrading legacy collections to the new Content Layer API.</ReadMore>
 
-
 ### Removed: `<ViewTransitions />` component
 
 <SourcePR number="14400" title="Remove deprecated ViewTransitions component"/>
@@ -554,7 +553,7 @@ Experimental flags allow you to opt in to features while they are in early devel
 
 Remove these experimental flags from your Astro config if you were previously using them:
 
-```js del={5-8} title="astro.config.mjs"
+```js del={5-9} title="astro.config.mjs"
 import { defineConfig } from 'astro/config';
 
 export default defineConfig({
@@ -563,6 +562,7 @@ export default defineConfig({
     preserveScriptOrder: true,
     staticImportMetaEnv: true,
     headingIdCompat: true,
+    failOnPrerenderConflict: true
   },
 })
 ```
@@ -576,10 +576,10 @@ export default defineConfig({
 - `preserveScriptOrder` (See below for breaking changes to [default `<script>` and `<style>` behavior](#changed-script-and-style-tags-are-rendered-in-the-order-they-are-defined).)
 - `staticImportMetaEnv` (See below for breaking changes to [`import.meta.env`](#changed-importmetaenv-values-are-always-inlined).)
 - `headingIdCompat` (See below for breaking changes to [Markdown heading ID generation](#changed-markdown-heading-id-generation).)
+- `prerenderConflictBehavior` (See below for breaking changes to [configurable prerendered routes conflict behavior](#changed-configurable-prerendered-routes-conflict-behavior).)
 
 <ReadMore>Read about exciting new features and more in [the v6.0 Blog post](https://astro.build/blog/astro-6/).</ReadMore>
 
-
 ## Changed Defaults
 
 Some default behavior has changed in Astro v5.0 and your project code may need updating to account for these changes.
@@ -924,6 +924,28 @@ export function getStaticPaths() {
 
 <ReadMore>Learn more about [dynamic SSG routes with `getStaticPaths()`](/en/guides/routing/#static-ssg-mode).</ReadMore>
 
+### Changed: configurable prerendered routes conflict behavior
+
+<SourcePR number="14826" title="feat(astro)!: stabilize failOnPrerenderConflict"/>
+
+In Astro 5.14, the `experimental.failOnPrerenderConflict` option was introduced to allow turning prerender conflict warnings into errors during the build process.
+
+Astro 6.0 stabilizes this option: it is now removed and replaced by `prerenderConflictBehavior`.
+
+#### What should I do?
+
+If you were previously using this experimental feature, you must [remove this experimental flag from your configuration](#experimental-flags) as it no longer exists and replace it with `prerenderConflictBehavior`:
+
+```js title="astro.config.mjs" ins={4}
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  prerenderConflictBehavior: 'error',
+});
+```
+
+<ReadMore>Learn more about the [route priority order](/en/guides/routing/#route-priority-order).</ReadMore>
+
 ## Community Resources
 
 Know a good resource for Astro v5.0? [Edit this page](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/upgrade-to/v6.mdx) and add a link below!
diff --git a/src/content/docs/en/reference/experimental-flags/fail-on-prerender-conflict.mdx b/src/content/docs/en/reference/experimental-flags/fail-on-prerender-conflict.mdx
deleted file mode 100644
index d55f79acbf8af..0000000000000
--- a/src/content/docs/en/reference/experimental-flags/fail-on-prerender-conflict.mdx
+++ /dev/null
@@ -1,37 +0,0 @@
----
-title: Experimental prerender conflict error
-sidebar:
-  label: Prerender conflict error
-i18nReady: true
----
-
-import Since from '~/components/Since.astro'
-
-<p>
-
-**Type:** `boolean`<br />
-**Default:** `false`<br />
-<Since v="5.14.0" />
-</p>
-
-Turns prerender conflict warnings into errors during the build process.
-
-Astro currently warns you during the build about any conflicts between multiple dynamic routes that can result in the same output path. For example `/blog/[slug]` and `/blog/[...all]` both could try to prerender the `/blog/post-1` path. In such cases, Astro renders only the [highest priority route](/en/guides/routing/#route-priority-order) for the conflicting path. This allows your site to build successfully, although you may discover that some pages are rendered by unexpected routes.
-
-With this experimental flag set, the build will instead fail immediately with an error. This will require you to resolve any routing conflicts immediately, and will ensure that Astro is building your routes as you intend.
-
-To enable this behavior, add the `experimental.failOnPrerenderConflict` feature flag to your Astro config:
-
-```js title="astro.config.mjs" ins={4-6}
-import { defineConfig } from "astro/config"
-
-defineConfig({
-	experimental: {
-		failOnPrerenderConflict: true,
-	},
-});
-```
-
-## Usage
-
-After enabling this flag, you may encounter errors about conflicting prerendered routes when you attempt to build your project. If this happens, you will need to update one or more of your [dynamic routes](/en/guides/routing/#dynamic-routes) to avoid ambiguous routing.
diff --git a/src/content/docs/fr/reference/experimental-flags/fail-on-prerender-conflict.mdx b/src/content/docs/fr/reference/experimental-flags/fail-on-prerender-conflict.mdx
deleted file mode 100644
index 77c9d8081d446..0000000000000
--- a/src/content/docs/fr/reference/experimental-flags/fail-on-prerender-conflict.mdx
+++ /dev/null
@@ -1,37 +0,0 @@
----
-title: Erreur de conflit de pré-rendu expérimentale
-sidebar:
-  label: Erreur de conflit de pré-rendu
-i18nReady: true
----
-
-import Since from '~/components/Since.astro'
-
-<p>
-
-**Type :** `boolean`<br />
-**Par défaut :** `false`<br />
-<Since v="5.14.0" />
-</p>
-
-Transforme les avertissements de conflit de pré-rendu en erreurs pendant le processus de compilation.
-
-Astro vous avertit actuellement, lors de la compilation, de tout conflit entre plusieurs routes dynamiques pouvant générer le même chemin de sortie. Par exemple, `/blog/[slug]` et `/blog/[...all]` pourraient tous deux tenter de générer le chemin `/blog/article-1`. Dans ce cas, Astro génère uniquement la [route la plus prioritaire](/fr/guides/routing/#ordre-de-priorité-des-routes) pour le chemin en conflit. Cela permet à votre site d'être compilé correctement, même si vous pourriez constater que certaines pages sont générées par des routes inattendues.
-
-Avec cette option expérimentale, la compilation échouera immédiatement avec une erreur. Cela vous obligera à résoudre immédiatement tout conflit de routage et garantira qu'Astro génère vos routes comme prévu.
-
-Pour activer ce comportement, ajoutez l'option de fonctionnalité `experimental.failOnPrerenderConflict` à votre configuration Astro :
-
-```js title="astro.config.mjs" ins={4-6}
-import { defineConfig } from "astro/config"
-
-defineConfig({
-	experimental: {
-		failOnPrerenderConflict: true,
-	},
-});
-```
-
-## Utilisation
-
-Après avoir activé cette option, vous risquez de rencontrer des erreurs concernant des routes pré-rendues en conflit lorsque vous tentez de compiler votre projet. Si cela se produit, vous devrez mettre à jour une ou plusieurs de vos [routes dynamiques](/fr/guides/routing/#routes-dynamiques) pour éviter tout routage ambigu.
diff --git a/src/content/docs/ko/reference/experimental-flags/fail-on-prerender-conflict.mdx b/src/content/docs/ko/reference/experimental-flags/fail-on-prerender-conflict.mdx
deleted file mode 100644
index da18e2d2e6a5b..0000000000000
--- a/src/content/docs/ko/reference/experimental-flags/fail-on-prerender-conflict.mdx
+++ /dev/null
@@ -1,37 +0,0 @@
----
-title: 실험적 사전 렌더링 충돌 오류
-sidebar:
-  label: 사전 렌더링 충돌 오류
-i18nReady: true
----
-
-import Since from '~/components/Since.astro'
-
-<p>
-
-**타입:** `boolean`<br />
-**기본값:** `false`<br />
-<Since v="5.14.0" />
-</p>
-
-빌드 과정에서 사전 렌더링 충돌 경고를 오류로 전환합니다.
-
-Astro는 빌드 과정에서 동일한 출력 경로를 생성할 수 있는 여러 동적 라우트 간 충돌에 대해 경고합니다. 예를 들어 `/blog/[slug]`와 `/blog/[...all]` 모두 `/blog/post-1` 경로를 사전 렌더링하려고 시도합니다. 이러한 경우 Astro는 충돌하는 경로에 대해 [가장 높은 우선순위의 라우트](/ko/guides/routing/#라우트-우선-순위)만 렌더링합니다. 이를 통해 사이트는 성공적으로 빌드되지만, 일부 페이지가 예상치 못한 라우트로 렌더링된다는 사실을 발견할 수 있습니다.
-
-이 실험적 플래그가 설정되면, 빌드는 즉시 실패하며, 오류가 발생합니다. 이로 인해 라우팅 충돌을 즉시 해결해야 하며, Astro가 라우트를 의도한 대로 빌드하도록 보장합니다.
-
-이 동작을 활성화하려면 Astro 구성에 `experimental.failOnPrerenderConflict` 기능 플래그를 추가하세요.
-
-```js title="astro.config.mjs" ins={4-6}
-import { defineConfig } from "astro/config"
-
-defineConfig({
-	experimental: {
-		failOnPrerenderConflict: true,
-	},
-});
-```
-
-## 사용하기
-
-이 플래그를 활성화한 후에는 프로젝트 빌드 시 사전 렌더링된 라우트 충돌에 대한 오류가 발생할 수 있습니다. 이 경우 모호한 라우팅을 방지하기 위해 하나 이상의 [동적 라우트](/ko/guides/routing/#동적-라우트)를 업데이트해야 합니다.

From f7c72a4baa3a480dd0af5357b3ca648cb8fd474d Mon Sep 17 00:00:00 2001
From: Florian Lefebvre <contact@florian-lefebvre.dev>
Date: Fri, 21 Nov 2025 09:15:23 +0100
Subject: [PATCH 2/5] feedback

---
 src/content/docs/en/guides/upgrade-to/v6.mdx | 24 +-------------------
 1 file changed, 1 insertion(+), 23 deletions(-)

diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx
index 0f8c6d78550e5..59b159dff19e9 100644
--- a/src/content/docs/en/guides/upgrade-to/v6.mdx
+++ b/src/content/docs/en/guides/upgrade-to/v6.mdx
@@ -570,13 +570,13 @@ export default defineConfig({
 #### Experimental features now stable:
 
 - `liveContentCollections` (See the updated [content collections docs](/en/guides/content-collections/) to learn more about live collections.)
+- `failOnPrerenderConflict` (See the new [`prerenderConflictBehavior`](/en/reference/configuration-reference/#prerenderconflictbehavior) configuration option.)
 
 #### New default or recommended behavior:
 
 - `preserveScriptOrder` (See below for breaking changes to [default `<script>` and `<style>` behavior](#changed-script-and-style-tags-are-rendered-in-the-order-they-are-defined).)
 - `staticImportMetaEnv` (See below for breaking changes to [`import.meta.env`](#changed-importmetaenv-values-are-always-inlined).)
 - `headingIdCompat` (See below for breaking changes to [Markdown heading ID generation](#changed-markdown-heading-id-generation).)
-- `prerenderConflictBehavior` (See below for breaking changes to [configurable prerendered routes conflict behavior](#changed-configurable-prerendered-routes-conflict-behavior).)
 
 <ReadMore>Read about exciting new features and more in [the v6.0 Blog post](https://astro.build/blog/astro-6/).</ReadMore>
 
@@ -924,28 +924,6 @@ export function getStaticPaths() {
 
 <ReadMore>Learn more about [dynamic SSG routes with `getStaticPaths()`](/en/guides/routing/#static-ssg-mode).</ReadMore>
 
-### Changed: configurable prerendered routes conflict behavior
-
-<SourcePR number="14826" title="feat(astro)!: stabilize failOnPrerenderConflict"/>
-
-In Astro 5.14, the `experimental.failOnPrerenderConflict` option was introduced to allow turning prerender conflict warnings into errors during the build process.
-
-Astro 6.0 stabilizes this option: it is now removed and replaced by `prerenderConflictBehavior`.
-
-#### What should I do?
-
-If you were previously using this experimental feature, you must [remove this experimental flag from your configuration](#experimental-flags) as it no longer exists and replace it with `prerenderConflictBehavior`:
-
-```js title="astro.config.mjs" ins={4}
-import { defineConfig } from 'astro/config';
-
-export default defineConfig({
-  prerenderConflictBehavior: 'error',
-});
-```
-
-<ReadMore>Learn more about the [route priority order](/en/guides/routing/#route-priority-order).</ReadMore>
-
 ## Community Resources
 
 Know a good resource for Astro v5.0? [Edit this page](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/upgrade-to/v6.mdx) and add a link below!

From edd9e68e02776c75416987638990338028d3a24d Mon Sep 17 00:00:00 2001
From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>
Date: Fri, 21 Nov 2025 07:53:03 -0400
Subject: [PATCH 3/5] Add placeholder config reference entry for link check

---
 .../en/reference/configuration-reference.mdx  | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/src/content/docs/en/reference/configuration-reference.mdx b/src/content/docs/en/reference/configuration-reference.mdx
index c6dbc501e3452..8e36b6eb0bd5c 100644
--- a/src/content/docs/en/reference/configuration-reference.mdx
+++ b/src/content/docs/en/reference/configuration-reference.mdx
@@ -366,6 +366,27 @@ Using `'class'` is helpful when you want to ensure that element selectors within
 Using `'where'` gives you more control over specificity, but requires that you use higher-specificity selectors, layers, and other tools to control which selectors are applied.
 Using `'attribute'` is useful when you are manipulating the `class` attribute of elements and need to avoid conflicts between your own styling logic and Astro's application of styles.
 
+### prerenderConflictBehavior
+
+<p>
+
+**Type:** `'error' | 'warning' | 'default'`<br />
+**Default:** `'warning'`<br />
+<Since v="6.0" />
+</p>
+
+Determines the default behavior when two routes generate the same prerendered URL:
+
+  - `error`: fail the build and display an error, forcing you to resolve the conflict
+  - `warning` (default): log a warning when conflicts occur, but build using the highest-priority route
+  - `ignore`: silently build using the highest-priority route when conflicts occur
+
+```js
+{
+  prerenderConflictBehavior: 'error'
+}
+```
+
 ### security
 
 <p>

From 157ce260abc98ae441f11beb9c9efc707177b686 Mon Sep 17 00:00:00 2001
From: Florian Lefebvre <contact@florian-lefebvre.dev>
Date: Fri, 21 Nov 2025 14:09:44 +0100
Subject: [PATCH 4/5] Apply suggestion from @florian-lefebvre

---
 src/content/docs/en/reference/configuration-reference.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/en/reference/configuration-reference.mdx b/src/content/docs/en/reference/configuration-reference.mdx
index 8e36b6eb0bd5c..d2944db58ce0c 100644
--- a/src/content/docs/en/reference/configuration-reference.mdx
+++ b/src/content/docs/en/reference/configuration-reference.mdx
@@ -370,7 +370,7 @@ Using `'attribute'` is useful when you are manipulating the `class` attribute of
 
 <p>
 
-**Type:** `'error' | 'warning' | 'default'`<br />
+**Type:** `'error' | 'warning' | 'ignore'`<br />
 **Default:** `'warning'`<br />
 <Since v="6.0" />
 </p>

From 6d8bab79ff7984eb9156fc844d9556b8534e31b6 Mon Sep 17 00:00:00 2001
From: Florian Lefebvre <contact@florian-lefebvre.dev>
Date: Fri, 21 Nov 2025 15:09:16 +0100
Subject: [PATCH 5/5] Apply suggestion from @florian-lefebvre

---
 src/content/docs/en/reference/configuration-reference.mdx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/content/docs/en/reference/configuration-reference.mdx b/src/content/docs/en/reference/configuration-reference.mdx
index d2944db58ce0c..ecc513b5d18da 100644
--- a/src/content/docs/en/reference/configuration-reference.mdx
+++ b/src/content/docs/en/reference/configuration-reference.mdx
@@ -370,15 +370,15 @@ Using `'attribute'` is useful when you are manipulating the `class` attribute of
 
 <p>
 
-**Type:** `'error' | 'warning' | 'ignore'`<br />
-**Default:** `'warning'`<br />
+**Type:** `'error' | 'warn' | 'ignore'`<br />
+**Default:** `'warn'`<br />
 <Since v="6.0" />
 </p>
 
 Determines the default behavior when two routes generate the same prerendered URL:
 
   - `error`: fail the build and display an error, forcing you to resolve the conflict
-  - `warning` (default): log a warning when conflicts occur, but build using the highest-priority route
+  - `warn` (default): log a warning when conflicts occur, but build using the highest-priority route
   - `ignore`: silently build using the highest-priority route when conflicts occur
 
 ```js