`astro build` fails unexpectedly with `build.format` set to `preserve`

[fulstadev]

Astro Info

Astro                    v7.2.0
Vite                     v8.2.1
Node                     v26.7.0
System                   macOS (arm64)
Package Manager          npm
Output                   static
Adapter                  none
Integrations             none

If this issue only occurs in one browser, which browser is a problem?

No response

Describe the Bug

After upgrading astro from version 5.17.1 to version 7.2.0 for a project, I became unable to build astro pages via astro build whose astro files:

1. sit within /src/pages/[format]/[lang]/
2. had the following content within their frontmatter:

export async function getStaticPaths() {
  return [
    { params: { format: 'first', lang: 'en' } },
    { params: { format: 'second', lang: 'en' } },
    { params: { format: 'third', lang: 'en' } },
    { params: { format: 'first', lang: 'de' } },
    { params: { format: 'second', lang: 'de' } },
    { params: { format: 'third', lang: 'de' } },
  ];
}

const {format, lang} = Astro.params;

When e.g. trying to astro build the page /src/pages/[format]/[lang]/welcome.astro, I got a build error saying:

first/en/welcome.html13:58:55 [ERROR] TypeError: Missing parameter: format

... indicating that while the path parameter format of the page /src/pages/[format]/[lang]/welcome.astro could be properly resolved, it could not be recognized by the astro build cycle.

After hours of console-logging and seeing that the path parameters are properly resolved and available while the page was being built, I found that the problem was that I set the build.format option in the astro config file to preserve. When uncommenting that, the build succeeded as in version 5.17.1.

I further investigated on this and indeed setting the build.format option to directory (which is the default value hence equivalent of omission tested above) indeed does the trick.

That feels like a bug to me, especially because it did not happen in version 5.17.1; so I wondered if this change is intentional ? If so, it would be very helpful if the SSG docs could e.g. include a note about an incompatibility with the build.format setting.

What's the expected result?

Pages should be generated normally as in version 5.17.1.

In the linked example, try simply changing the value of the build.format config from preserve to directory and vice-versa in the projects' astro.config.mjs file, then re-run npm run build to try to rebuild the project and you will see what I mean.

Link to Minimal Reproducible Example

https://stackblitz.com/edit/github-hdpeidlx?file=astro.config.mjs

Participation

• I am willing to submit a pull request for this issue.

[astrobot-houston]

• Reproduced: No — the build succeeds on current main (v7.2.2) with the exact reproduction steps from the issue.
• Exploration: Yes — View branch
• Unit Test: No — the bug does not reproduce on main, so no failing test could be written.
• Priority: P2: has workaround. The reporter can work around this by using build.format: 'directory' (the default), and the issue appears to already be resolved on the latest version.

The reported error (TypeError: Missing parameter: format) occurs in packages/astro/src/core/routing/generator.ts when a dynamic route parameter cannot be found in the params object during static path generation. The issue describes a naming collision between a route parameter named format (from src/pages/[format]/[lang]/welcome.astro) and the build.format config option set to 'preserve'. Testing on the current main branch (v7.2.2) with the exact reproduction setup — build.format: 'preserve', a [format]/[lang]/welcome.astro route with getStaticPaths() returning 6 paths — produces a fully successful build with all 6 pages generated correctly and the format param properly resolved in the output HTML.

This issue has already been fixed. The bug was reported against v7.2.0, but the build succeeds on the current main (v7.2.2). Upgrading to the latest Astro version should resolve this issue.

Full Triage Report

Reproduction Attempt

Created a minimal project at examples/repro-17726 with:

• astro.config.mjs with build.format: 'preserve'
• src/pages/[format]/[lang]/welcome.astro with getStaticPaths() returning 6 param combinations

Build Output (v7.2.2 — current main)

generating static routes
  ├─ /first/en/welcome.html (+8ms)
  ├─ /second/en/welcome.html (+2ms)
  ├─ /third/en/welcome.html (+1ms)
  ├─ /first/de/welcome.html (+1ms)
  ├─ /second/de/welcome.html (+1ms)
  ├─ /third/de/welcome.html (+1ms)
✓ Completed in 32ms.
6 page(s) built in 368ms
Complete!

All output files were verified to contain the correct format parameter value (e.g., <h1>Welcome - second</h1>).

Relevant Code Path

The error TypeError: Missing parameter: format originates in packages/astro/src/core/routing/generator.ts:28 in the getParameter() function, which throws when params[part.content] is undefined for a dynamic route part. The params are populated via stringifyParams() in packages/astro/src/core/routing/params.ts, which calls getRouteGenerator().

Version Comparison

The reporter used v7.2.0. Between v7.2.0 and v7.2.2, several fixes were merged. While no single commit directly addresses this exact naming collision, the fix appears to be included in the changes between these versions. An attempt to check out v7.2.0's packages failed due to lockfile incompatibilities, so the exact fixing commit could not be identified.

This report was made by an LLM. The analysis may be wrong, and the potential fix might not work, but is intended as a starting point for exploring the issue.

[ArmandPhilippot]

Ah, I didn't knew this was working before, so I haven't took the time to report this. I encountered a similar issue a few days ago. This is because you use trailingSlash: "always" in addition to build.format: "preserve". But, your description doesn't mention trailingSlash and it seems the bot used its own reproduction (without that important parameter) instead of yours.

Using your reproduction, it seems to be a v7 regression (at least it works with 6.0.1).

@astrobot-houston can you triage this again with these additional data?

[fulstadev]

That is true, my own project (as well as the linked stackblitz example) includes the trailingSlash: always config value. Is there anything planned to fix this issue ?

[astrobot-houston]

• Reproduced: Yes — the build fails with TypeError: Missing parameter: format when both build.format: 'preserve' and trailingSlash: 'always' are set, confirming @ArmandPhilippot's observation that both settings are required to trigger the bug.
• Exploration: Yes — View branch
• Unit Test: Yes — packages/astro/test/units/fetch/index.test.ts ('restores trailing slash after stripping .html when trailingSlash is always')
• Priority: P4: important. This is a regression from PR fix: correct Astro.url.pathname for non-index pages with build.format: 'preserve' #17560 that completely breaks astro build for any project using build.format: 'preserve' + trailingSlash: 'always' with dynamic routes. It affects a documented, supported configuration combination and produces a build-time crash with no recovery path other than changing config.

This is a regression introduced by #17560. When build.format: 'preserve' and trailingSlash: 'always' are both set, the build pipeline generates internal request URLs ending in .html for non-index pages. FetchState.#stripHtmlExtension() in packages/astro/src/core/fetch/fetch-state.ts removes the .html suffix but doesn't restore the trailing / that the route pattern (compiled with trailingSlash: 'always') requires. This causes getParams() to fail pattern matching, returning empty params, which then throws TypeError: Missing parameter when stringifyParams() tries to look up the dynamic route parameters.

I found a potential fix for this issue. After stripping .html, #stripHtmlExtension() now checks if trailingSlash is 'always' and appends a trailing / when missing, so the pathname matches the compiled route pattern. All existing tests pass, including the preserve and preserve - i18n suites in page-format.test.ts.

Try this fix

You can test this fix right now without waiting for a release:

npm i https://pkg.pr.new/astro@597b312

If this fixes your issue, please leave a comment letting us know (e.g. "confirmed, this fixes it"). We'll then open a pull request to get this merged.

Full Triage Report

Issue Summary

Title: astro build fails unexpectedly with build.format set to preserve

Reporter: @fulstadev

After upgrading from Astro 5.17.1 to 7.2.0, running astro build fails with TypeError: Missing parameter: format when a dynamic route uses a parameter named format (e.g., src/pages/[format]/[lang]/dummy.astro) and the config has build.format: 'preserve'. The reporter's StackBlitz reproduction also includes trailingSlash: 'always', which @ArmandPhilippot identified as the critical additional factor.

Reproduction

The bug reproduces on current main when both build.format: 'preserve' and trailingSlash: 'always' are set in astro.config.mjs. The previous triage attempt failed because it omitted trailingSlash: 'always'.

Baseline Verification

• build.format: 'directory' + trailingSlash: 'always' → ✅ Build succeeds
• build.format: 'preserve' + no trailingSlash setting → ✅ Build succeeds
• build.format: 'preserve' + trailingSlash: 'always' → ❌ Build fails

Root Cause

The bug is a regression from PR #17560 (commit ef45de17d21). The code path:

1. stringifyParams() generates pathname /first/en/dummy/ (trailing / from trailingSlash: 'always')
2. getUrlForPath() resolves preserve non-index → effectiveFormat = 'file' → URL becomes /first/en/dummy.html
3. FetchState.#stripHtmlExtension() strips .html → pathname becomes /first/en/dummy (no trailing slash)
4. getParams() tries to match /first/en/dummy against pattern /^\/([^/]+?)\/([^/]+?)\/dummy\/$/ → no match → empty params
5. stringifyParams({}) → TypeError: Missing parameter: format

Fix

In packages/astro/src/core/fetch/fetch-state.ts, #stripHtmlExtension() now restores the trailing / after stripping .html when trailingSlash === 'always':

 this.pathname = this.pathname.replace(/\/index\.html$/, '/').replace(/\.html$/, '');
+// When trailingSlash is 'always', the route pattern requires a trailing '/'.
+// After stripping '.html', restore it so getParams() can match. (#17726)
+if (this.manifest.trailingSlash === 'always' && !this.pathname.endsWith('/')) {
+    this.pathname += '/';
+}

Verification

• ✅ Reproduction build succeeds: all 6 dynamic pages generated correctly
• ✅ All page-format.test.ts tests pass (9/9)
• ✅ All fetch/index.test.ts tests pass (61/61)
• ✅ Biome lint passes

Unit Test

Added 'restores trailing slash after stripping .html when trailingSlash is always' in packages/astro/test/units/fetch/index.test.ts.

This report was made by an LLM. The analysis may be wrong, and the potential fix might not work, but is intended as a starting point for exploring the issue.

[ArmandPhilippot]

@fulstadev Of course! I was waiting for the bot to triage the issue again. You can follow the instructions in "Try this fix" of the bot's answer to see if this works in your project. And once confirmed, a PR will be created!