Start: page route returns 500 when Accept excludes HTML #7913
Send to my agentWhich project does this relate to?#
Start
Describe the bug#
createStartHandler refuses to render a page route when the request's Accept
header does not allow HTML, and reports that refusal as 500:
A failed content negotiation is a client-side condition, so this should be
406 Not Acceptable. 500 says the server malfunctioned, and nothing did.
Complete minimal reproducer#
reproduction doesn't need any custom code
Steps to Reproduce the Bug#
Against any Start app, on any page (non-server) route:
curl -i -H 'Accept: application/json' https://example.com/
curl -i -H 'Accept: image/webp' https://example.com/
Both return 500 {"error":"Only HTML requests are supported here"}. Accept: /, a browser Accept, and an absent header all return 200.
Expected behavior#
Should return 406 Not Acceptable instead of 500 Server Error.
Screenshots or Videos#
No response
Platform#
- @tanstack/react-start 1.168.32
- @tanstack/start-server-core 1.169.17 (current latest)
Additional context#
No response
Several LLM fetchers send Accept: text/markdown with no / fallback.
which ones?
I can't back that up, so I withdraw it.
Checkly's February survey of seven coding agents found three that request markdown, and all three carry a fallback:
- Claude Code —
text/markdown, text/html, */* - Cursor —
text/markdown,text/html;q=0.9,…,*/*;q=0.5 - OpenCode —
text/markdown;q=1.0,…,text/html;q=0.7,*/*;q=0.1
Every one passes the current check. I found no named fetcher sending bare
text/markdown.What actually hit me was an agent-readiness audit probing negotiation without a fallback — a conformance checker, not crawler traffic. Much narrower than what I wrote.
The middleware point doesn't depend on it, though.
executeRouteris invoked asexecuteRouter(ctx.context, matchedRoutes)and takes no request, so theAcceptcheck readsrequestfrom thestartRequestResolverclosure. Middleware can run first and produce a modified request, and the check still inspects the original — the server entry is the only place to intervene. (Checked against 1.168.x.)And @ollipa's original report —
application/json/image/webpreturning 500 — stands regardless of any of this;406is still the right answer there.So treat
supportedMimeTypesas resting on the middleware limitation rather than on traffic, and close it if that's too thin.- Claude Code —
This issue was fixed by @schiller-manuel as part of https://github.com/TanStack/router/pull/8204
okxint(GitHub profile, opens in a new tab) linked this to #7925
Sign in to join this conversation.
Hitting this on a public marketing site that publishes agent-readable documents (
llms.txt, an agent guide, a small OpenAPI spec) next to the normal HTML pages.Several LLM fetchers send
Accept: text/markdownwith no*/*fallback. Every page route answers them with500 {"error":"Only HTML requests are supported here"}. An automated agent-readiness audit flagged the site as failing content negotiation, which is how I found it. From the client side the whole site looks broken, not merely non-negotiable.Two things I ran into while working around it:
Global request middleware cannot fix this.
executeRouterreadsrequestfrom thestartRequestResolverclosure, so theAcceptcheck always inspects the originalRequest, even when middleware ran first and produced a modified one. The only place to intervene is the server entry, rewriting the header beforehandler.fetch.406alone would not help much. It is the correct status and I would still like it. But an app that wants to serve something for these requests (a markdown rendering of the page, or a redirect to a.mdvariant) needs a way to opt out of the check, not a politer refusal.Would you consider making the accepted list configurable on
createStart?Default unchanged, and
406when negotiation genuinely fails. That would let apps handle markdown in a route or middleware, and keep current behaviour for everyone else.