Skip to content
Source
Sign inSign up
TanStack/router

Start: page route returns 500 when Accept excludes HTML #7913

Send to my agent
Openollipa(GitHub profile, opens in a new tab) opened this issue 4 comments

Which 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:

https://github.com/TanStack/router/blob/179d9b9b5eec50dc7833b4e2ef91b735d34bbc07/packages/start-server-core/src/createStartHandler.ts#L558-L561

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

  1. 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/markdown with no */* fallback. Every page route answers them with 500 {"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:

    1. Global request middleware cannot fix this. executeRouter reads request from the startRequestResolver closure, so the Accept check always inspects the original Request, even when middleware ran first and produced a modified one. The only place to intervene is the server entry, rewriting the header before handler.fetch.

    2. 406 alone 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 .md variant) needs a way to opt out of the check, not a politer refusal.

    Would you consider making the accepted list configurable on createStart?

    createStart(() => ({
      supportedMimeTypes: ['*/*', 'text/html', 'text/markdown'],
    }))

    Default unchanged, and 406 when negotiation genuinely fails. That would let apps handle markdown in a route or middleware, and keep current behaviour for everyone else.

  2. Several LLM fetchers send Accept: text/markdown with no / fallback.

    which ones?

  3. 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. executeRouter is invoked as executeRouter(ctx.context, matchedRoutes) and takes no request, so the Accept check reads request from the startRequestResolver closure. 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/webp returning 500 — stands regardless of any of this; 406 is still the right answer there.

    So treat supportedMimeTypes as resting on the middleware limitation rather than on traffic, and close it if that's too thin.

Sign in to join this conversation.