fix(start-server-core): fall back to GET handler for HEAD requests (RFC 9110 §9.3.2)

.changeset/fix-head-request-server-route-fallback.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/start-server-core': patch
+---
+
+fix(start-server-core): fall back HEAD requests to GET then ANY per RFC 9110 §9.3.2

e2e/react-start/server-routes/src/routeTree.gen.ts

@@ -16,6 +16,9 @@ import { Route as MethodsIndexRouteImport } from './routes/methods/index'
 import { Route as MethodsOnlyAnyRouteImport } from './routes/methods/only-any'
 import { Route as ApiOnlyAnyRouteImport } from './routes/api/only-any'
 import { Route as ApiMiddlewareContextRouteImport } from './routes/api/middleware-context'
+import { Route as ApiHeadFallbackRouteImport } from './routes/api/head-fallback'
+import { Route as ApiGetAndAnyRouteImport } from './routes/api/get-and-any'
+import { Route as ApiHeadRedirectFallbackRouteImport } from './routes/api/head-redirect-fallback'
 import { Route as ApiParamsFooRouteRouteImport } from './routes/api/params/$foo/route'
 import { Route as ApiParamsFooBarRouteImport } from './routes/api/params/$foo/$bar'
 
@@ -49,6 +52,21 @@ const ApiOnlyAnyRoute = ApiOnlyAnyRouteImport.update({
   path: '/api/only-any',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiHeadFallbackRoute = ApiHeadFallbackRouteImport.update({
+  id: '/api/head-fallback',
+  path: '/api/head-fallback',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiGetAndAnyRoute = ApiGetAndAnyRouteImport.update({
+  id: '/api/get-and-any',
+  path: '/api/get-and-any',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiHeadRedirectFallbackRoute = ApiHeadRedirectFallbackRouteImport.update({
+  id: '/api/head-redirect-fallback',
+  path: '/api/head-redirect-fallback',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiMiddlewareContextRoute = ApiMiddlewareContextRouteImport.update({
   id: '/api/middleware-context',
   path: '/api/middleware-context',
@@ -71,6 +89,9 @@ export interface FileRoutesByFullPath {
   '/merge-middleware-context': typeof MergeMiddlewareContextRoute
   '/api/middleware-context': typeof ApiMiddlewareContextRoute
   '/api/only-any': typeof ApiOnlyAnyRoute
+  '/api/head-fallback': typeof ApiHeadFallbackRoute
+  '/api/get-and-any': typeof ApiGetAndAnyRoute
+  '/api/head-redirect-fallback': typeof ApiHeadRedirectFallbackRoute
   '/methods/only-any': typeof MethodsOnlyAnyRoute
   '/methods/': typeof MethodsIndexRoute
   '/api/params/$foo': typeof ApiParamsFooRouteRouteWithChildren
@@ -81,6 +102,9 @@ export interface FileRoutesByTo {
   '/merge-middleware-context': typeof MergeMiddlewareContextRoute
   '/api/middleware-context': typeof ApiMiddlewareContextRoute
   '/api/only-any': typeof ApiOnlyAnyRoute
+  '/api/head-fallback': typeof ApiHeadFallbackRoute
+  '/api/get-and-any': typeof ApiGetAndAnyRoute
+  '/api/head-redirect-fallback': typeof ApiHeadRedirectFallbackRoute
   '/methods/only-any': typeof MethodsOnlyAnyRoute
   '/methods': typeof MethodsIndexRoute
   '/api/params/$foo': typeof ApiParamsFooRouteRouteWithChildren
@@ -93,6 +117,9 @@ export interface FileRoutesById {
   '/merge-middleware-context': typeof MergeMiddlewareContextRoute
   '/api/middleware-context': typeof ApiMiddlewareContextRoute
   '/api/only-any': typeof ApiOnlyAnyRoute
+  '/api/head-fallback': typeof ApiHeadFallbackRoute
+  '/api/get-and-any': typeof ApiGetAndAnyRoute
+  '/api/head-redirect-fallback': typeof ApiHeadRedirectFallbackRoute
   '/methods/only-any': typeof MethodsOnlyAnyRoute
   '/methods/': typeof MethodsIndexRoute
   '/api/params/$foo': typeof ApiParamsFooRouteRouteWithChildren
@@ -106,6 +133,9 @@ export interface FileRouteTypes {
     | '/merge-middleware-context'
     | '/api/middleware-context'
     | '/api/only-any'
+    | '/api/head-fallback'
+    | '/api/get-and-any'
+    | '/api/head-redirect-fallback'
     | '/methods/only-any'
     | '/methods/'
     | '/api/params/$foo'
@@ -116,6 +146,9 @@ export interface FileRouteTypes {
     | '/merge-middleware-context'
     | '/api/middleware-context'
     | '/api/only-any'
+    | '/api/head-fallback'
+    | '/api/get-and-any'
+    | '/api/head-redirect-fallback'
     | '/methods/only-any'
     | '/methods'
     | '/api/params/$foo'
@@ -127,6 +160,9 @@ export interface FileRouteTypes {
     | '/merge-middleware-context'
     | '/api/middleware-context'
     | '/api/only-any'
+    | '/api/head-fallback'
+    | '/api/get-and-any'
+    | '/api/head-redirect-fallback'
     | '/methods/only-any'
     | '/methods/'
     | '/api/params/$foo'
@@ -139,6 +175,9 @@ export interface RootRouteChildren {
   MergeMiddlewareContextRoute: typeof MergeMiddlewareContextRoute
   ApiMiddlewareContextRoute: typeof ApiMiddlewareContextRoute
   ApiOnlyAnyRoute: typeof ApiOnlyAnyRoute
+  ApiHeadFallbackRoute: typeof ApiHeadFallbackRoute
+  ApiGetAndAnyRoute: typeof ApiGetAndAnyRoute
+  ApiHeadRedirectFallbackRoute: typeof ApiHeadRedirectFallbackRoute
   ApiParamsFooRouteRoute: typeof ApiParamsFooRouteRouteWithChildren
 }
 
@@ -186,6 +225,27 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiOnlyAnyRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/head-fallback': {
+      id: '/api/head-fallback'
+      path: '/api/head-fallback'
+      fullPath: '/api/head-fallback'
+      preLoaderRoute: typeof ApiHeadFallbackRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/api/get-and-any': {
+      id: '/api/get-and-any'
+      path: '/api/get-and-any'
+      fullPath: '/api/get-and-any'
+      preLoaderRoute: typeof ApiGetAndAnyRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/api/head-redirect-fallback': {
+      id: '/api/head-redirect-fallback'
+      path: '/api/head-redirect-fallback'
+      fullPath: '/api/head-redirect-fallback'
+      preLoaderRoute: typeof ApiHeadRedirectFallbackRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/middleware-context': {
       id: '/api/middleware-context'
       path: '/api/middleware-context'
@@ -241,6 +301,9 @@ const rootRouteChildren: RootRouteChildren = {
   MergeMiddlewareContextRoute: MergeMiddlewareContextRoute,
   ApiMiddlewareContextRoute: ApiMiddlewareContextRoute,
   ApiOnlyAnyRoute: ApiOnlyAnyRoute,
+  ApiHeadFallbackRoute: ApiHeadFallbackRoute,
+  ApiGetAndAnyRoute: ApiGetAndAnyRoute,
+  ApiHeadRedirectFallbackRoute: ApiHeadRedirectFallbackRoute,
   ApiParamsFooRouteRoute: ApiParamsFooRouteRouteWithChildren,
 }
 export const routeTree = rootRouteImport

e2e/react-start/server-routes/src/routes/api/get-and-any.ts

@@ -0,0 +1,16 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/api/get-and-any')({
+  server: {
+    handlers: {
+      GET: () =>
+        new Response(null, {
+          headers: { 'x-handler': 'GET' },
+        }),
+      ANY: ({ request }) =>
+        new Response(null, {
+          headers: { 'x-handler': 'ANY', 'x-method': request.method },
+        }),
+    },
+  },
+})

e2e/react-start/server-routes/src/routes/api/head-fallback.ts

@@ -0,0 +1,14 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+// A server-only route with only a GET handler.
+// Used to test that HEAD requests fall back to the GET handler per RFC 9110.
+export const Route = createFileRoute('/api/head-fallback')({
+  server: {
+    handlers: {
+      GET: () =>
+        new Response('body', {
+          headers: { 'content-type': 'application/xml; charset=utf-8' },
+        }),
+    },
+  },
+})

e2e/react-start/server-routes/src/routes/api/head-redirect-fallback.ts

@@ -0,0 +1,9 @@
+import { createFileRoute, redirect } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/api/head-redirect-fallback')({
+  server: {
+    handlers: {
+      GET: () => redirect({ to: '/api/head-fallback', statusCode: 307 }),
+    },
+  },
+})

e2e/react-start/server-routes/tests/server-routes.spec.ts

@@ -17,6 +17,79 @@ test('merge-middleware-context', async ({ page }) => {
   expect(contextResult).toContain('test')
 })
 
+test.describe('HEAD fallback', () => {
+  test('strips body and preserves headers when falling back to GET', async ({
+    page,
+  }) => {
+    await page.goto('/')
+    const result = await page.evaluate(async () => {
+      const res = await fetch('/api/head-fallback', { method: 'HEAD' })
+      return {
+        status: res.status,
+        contentType: res.headers.get('content-type'),
+        body: await res.text(),
+      }
+    })
+    expect(result.status).toBe(200)
+    expect(result.contentType).toBe('application/xml; charset=utf-8')
+    expect(result.body).toBe('')
+  })
+
+  test('strips body and preserves headers when falling back to ANY', async ({
+    page,
+  }) => {
+    await page.goto('/')
+    const result = await page.evaluate(async () => {
+      const res = await fetch('/api/only-any', { method: 'HEAD' })
+      return {
+        status: res.status,
+        xHandler: res.headers.get('x-handler'),
+        xMethod: res.headers.get('x-method'),
+        body: await res.text(),
+      }
+    })
+    expect(result.status).toBe(200)
+    expect(result.xHandler).toBe('ANY')
+    expect(result.xMethod).toBe('HEAD')
+    expect(result.body).toBe('')
+  })
+
+  test('prefers GET over ANY for HEAD requests', async ({ page }) => {
+    await page.goto('/')
+    const result = await page.evaluate(async () => {
+      const res = await fetch('/api/get-and-any', { method: 'HEAD' })
+      return {
+        status: res.status,
+        xHandler: res.headers.get('x-handler'),
+        body: await res.text(),
+      }
+    })
+    expect(result.status).toBe(200)
+    expect(result.xHandler).toBe('GET')
+    expect(result.body).toBe('')
+  })
+
+  test('preserves Location header when GET handler returns a redirect', async ({
+    page,
+  }) => {
+    await page.goto('/')
+    // HEAD /api/head-redirect-fallback → server returns 307 Location:/api/head-fallback
+    // Browser follows the redirect: HEAD /api/head-fallback → 200 with correct headers
+    // If the Location header were lost, the browser could not follow and would see a 307.
+    const result = await page.evaluate(async () => {
+      const res = await fetch('/api/head-redirect-fallback', { method: 'HEAD' })
+      return {
+        status: res.status,
+        contentType: res.headers.get('content-type'),
+        body: await res.text(),
+      }
+    })
+    expect(result.status).toBe(200)
+    expect(result.contentType).toBe('application/xml; charset=utf-8')
+    expect(result.body).toBe('')
+  })
+})
+
 test.describe('methods', () => {
   test('only ANY', async ({ page }) => {
     await page.goto('/methods/only-any')

packages/start-server-core/src/createStartHandler.ts

@@ -891,14 +891,22 @@ async function handleServerRoutes({
 
   // Add handler middleware if exact match
   const server = foundRoute?.options.server
+  let isHeadFallback = false
   if (server?.handlers && isExactMatch) {
     const handlers =
       typeof server.handlers === 'function'
         ? server.handlers({ createHandlers: (d: any) => d })
         : server.handlers
 
     const requestMethod = request.method.toUpperCase() as RouteMethod
-    const handler = handlers[requestMethod] ?? handlers['ANY']
+    // Per RFC 9110 §9.3.2, HEAD must return the same header fields as GET.
+    // Priority for HEAD: explicit HEAD handler → GET → ANY (last resort).
+    const handler =
+      requestMethod === 'HEAD'
+        ? (handlers['HEAD'] ?? handlers['GET'] ?? handlers['ANY'])
+        : (handlers[requestMethod] ?? handlers['ANY'])
+    isHeadFallback =
+      requestMethod === 'HEAD' && handler !== undefined && !handlers['HEAD']
 
     if (handler) {
       const mayDefer = !!foundRoute.options.component
@@ -931,5 +939,16 @@ async function handleServerRoutes({
     pathname,
   })
 
+  // RFC 9110 §9.3.2: HEAD must carry the same header fields as GET but no body.
+  // Resolve any redirect before stripping so the Location header survives.
+  if (isHeadFallback) {
+    const resolved = await handleRedirectResponse(
+      ctx.response as Response,
+      request,
+      getRouter,
+    )
+    return new Response(null, resolved)
+  }
+
   return ctx.response
 }