Path mismatch error when returning HTML file path in static file endpoint that uses dynamic routing

[noahmulfinger]

Astro Info

Astro                    v6.0.4
Node                     v22.22.0
System                   Linux (x64)
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

When I return an HTML file from a static file endpoint that makes use of getStaticPaths to do dynamic routing, the .html ending is removed, causing a path mismatch and resulting in a NoMatchingStaticPathFound error. For example, if I have a path file.html returned as the param value in one of the getStaticPaths entries, I get the below error. If I change the param value to just file, the build succeeds but I end up with a file called file in the output that has no extension.

generating static routes 
17:20:08   ├─ /index.html (+6ms) 
17:20:08   ├─ /file.html17:20:08 [ERROR] NoMatchingStaticPathFound: A `getStaticPaths()` route pattern was matched, but no matching static path was found for requested path `/file`.
    at AstroError (file:///home/projects/github-dnjnvdtp/dist/.prerender/chunks/prerender_BZ2JtAqQ.mjs:77:5)
    at getProps (file:///home/projects/github-dnjnvdtp/dist/.prerender/chunks/prerender_BZ2JtAqQ.mjs:6844:11)
17:20:08 [ERROR] [build] Caught error rendering /file.html: NoMatchingStaticPathFound: A `getStaticPaths()` route pattern was matched, but no matching static path was found for requested path `/file`.
[NoMatchingStaticPathFound] A `getStaticPaths()` route pattern was matched, but no matching static path was found for requested path `/file`.
  Hint:
    Possible dynamic routes being matched: src/pages/[...path].ts.
  Error reference:
    https://docs.astro.build/en/reference/errors/no-matching-static-path-found/
  Stack trace:
    at AstroError (file:///home/projects/github-dnjnvdtp/dist/.prerender/chunks/prerender_BZ2JtAqQ.mjs:77:5)

What's the expected result?

I would expect using a param value like file.html from a static file endpoint to result in a successful build with a file called file.html in the output. This was the case in Astro v5. I've created both a v5 and v6 StackBlitz for comparison:

• Using Astro v5: https://stackblitz.com/edit/github-dnjnvdtp-qukvnco1 - npm run build succeeds
• Using Astro v6: https://stackblitz.com/edit/github-dnjnvdtp - npm run build fails

Link to Minimal Reproducible Example

https://stackblitz.com/edit/github-dnjnvdtp

Participation

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

[astrobot-houston]

I was able to reproduce this issue. The root cause is an unconditional .html stripping in the getParams function (packages/astro/src/core/render/params-and-props.ts), introduced in PR #14799 as part of the Environment API work. When a user provides { path: 'file.html' } in getStaticPaths, the build generates pathname /file.html, but getParams strips the .html suffix, producing params { path: 'file' } instead of { path: 'file.html' }. This causes findPathItemByKey to fail because the cached static path key is file.html, not file, resulting in the NoMatchingStaticPathFound error. This is a regression from Astro v5, where the stripping did not exist.

I was able to fix this issue. The fix removes the unconditional .html stripping from getParams and instead uses a fallback approach in getProps: it first tries matching with the original pathname (preserving .html), and only if that fails, tries stripping .html and matching again. The output path utilities are also updated to handle pathnames that already end with .html. View Suggested Fix

P4: important. This is a v5-to-v6 regression that breaks any static file endpoint using dynamic routing where the param value intentionally includes a .html extension. It violates the previously documented and working behavior, and there is no clean workaround — omitting .html from the param value produces a file with no extension in the output.

Full Triage Report

Issue #15893: Path mismatch error when returning HTML file path in static file endpoint that uses dynamic routing

Issue Summary

Reporter: noahmulfinger
URL: #15893
Created: 2026-03-13

Reproduction

A static file endpoint src/pages/[...path].ts with getStaticPaths returning { params: { path: 'file.html' } } fails during build with:

NoMatchingStaticPathFound: A `getStaticPaths()` route pattern was matched, but no matching static path was found for requested path `/file`.

Reproduction Steps

1. Create a [...path].ts endpoint that returns { params: { path: 'file.html' } } from getStaticPaths
2. Run astro build
3. Build fails with NoMatchingStaticPathFound error

Reproduction Result

Bug reproduced on the current main branch. Build fails with the exact error described in the issue.

Claim

• Current behavior: Using a param value like file.html from a static file endpoint causes the .html ending to be stripped during param extraction, resulting in a NoMatchingStaticPathFound error because /file doesn't match the expected file.html param.
• Expected behavior: Returning file.html as a param value should work and produce a file called file.html in the output, as it did in Astro v5.

Verification

Verdict: bug

Confidence: high

Evidence

1. Regression from v5 to v6

Before the Environment API PR (141c4a26419), the getParams function in packages/astro/src/core/render/params-and-props.ts did NOT strip .html from pathnames. The original code simply ran route.pattern.exec(pathname) directly. This means .html params worked correctly in v5.

2. Root cause: PR #14799 introduced unconditional .html stripping

Commit 771832e0da ("fix: logger level and static paths params", PR #14799), part of the Environment API branch, introduced the following code in getParams:

// The path could contain `.html` at the end. We remove it so we can correctly the parameters
// with the generated keyed parameters.
if (pathname.endsWith('.html')) {
    path = path.slice(0, -5);
}

This was intended to handle buildFormat: 'file' where Astro appends .html to URLs, but it unconditionally strips .html from ALL pathnames — including those where .html is an intentional part of the user's param value (e.g., user slug file.html).

The comment itself is grammatically incomplete ("we can correctly the parameters"), suggesting it was a quick fix that didn't fully consider edge cases.

3. The scenario was never considered

There are no tests, comments, or explicit handling for the case where a user intentionally includes .html in their getStaticPaths param values. The stripping logic has no awareness of whether .html is framework-appended or user-provided.

4. Fix already exists on a feature branch

A fix commit (d59287a155, branch flue/fix-15840) titled "fix(routing): allow .html in dynamic route slugs for getStaticPaths" already exists. This fix:

• Removes the unconditional .html stripping from getParams
• Adds a fallback approach in getProps: first tries matching with the original pathname (preserving .html), and only if that fails, tries stripping .html and matching again
• Updates getOutFolder, getOutFile, and getOutputFilename to handle pathnames that already end with .html

This confirms the Astro team has already identified this as a bug and is working on a fix.

5. The flow that causes the error

1. User provides { path: 'file.html' } in getStaticPaths
2. stringifyParams generates pathname /file.html
3. During rendering, getProps is called with pathname /file.html
4. getParams strips .html, turning the pathname into /file
5. Params extracted from /file produce { path: 'file' } instead of { path: 'file.html' }
6. findPathItemByKey fails to find a match because the cached static path has key file.html, not file
7. NoMatchingStaticPathFound error is thrown

Affected Code

• packages/astro/src/core/render/params-and-props.ts:91-95 — The unconditional .html stripping in getParams

This report was made by an LLM. Mistakes happen, check important info.

[fkatsuhiro]

Hi! I'm interested in this issue!
I'll investigate this.

[noahmulfinger]

One thing I did notice was that PR #15944 fixed a similar issue with dynamic endpoints and .html endings. However, in this issue there is no .html in the route pattern itself, so it doesn't fix it. I played around with building off that PR by adding a routeData.type !== 'endpoint' to the if condition (which seems to match the astrobot's suggested fix), which does seem to work. I don't know enough about the Astro codebase to know if that's the best solution.