next.js: Route handler always returns `X-Vercel-Cache: STALE`

Link to the code that reproduces this issue

https://github.com/joostmeijles/route-handler-stale/tree/main

Route handler example: https://github.com/joostmeijles/route-handler-stale/blob/main/app/items/[slug]/route.ts

To Reproduce

  1. Start the application in production mode
  2. Visit http://localhost:3000/items/a
  3. Inspect the response headers and verify that first visit has x-nextjs-cache: MISS
  4. Visit http://localhost:3000/items/a
  5. Inspect the response headers and verify that first visit has x-nextjs-cache: HIT
  6. Deploy to Vercel
  7. Visit https://routehandler-stale.vercel.app/items/a
  8. Inspect the response headers and verify that it has always X-Vercel-Cache: STALE

Current vs. Expected behavior

Currently always X-Vercel-Cache: STALE is returned.

Expected is X-Vercel-Cache: MISS on first visit and X-Vercel-Cache: HIT for subsequent visits.

Provide environment information

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 22.2.0: Fri Nov 11 02:04:44 PST 2022; root:xnu-8792.61.2~4/RELEASE_ARM64_T8103
  Available memory (MB): 8192
  Available CPU cores: 8
Binaries:
  Node: 20.12.2
  npm: 10.5.0
  Yarn: N/A
  pnpm: 8.15.7
Relevant Packages:
  next: 14.3.0-canary.63 // Latest available version is detected (14.3.0-canary.63).
  eslint-config-next: N/A
  react: 19.0.0-beta-4508873393-20240430
  react-dom: 19.0.0-beta-4508873393-20240430
  typescript: 5.1.3
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

App Router

Which stage(s) are affected? (Select all that apply)

Vercel (Deployed)

Additional context

No response

About this issue

  • Original URL
  • State: closed
  • Created 3 years ago
  • Reactions: 3
  • Comments: 37 (33 by maintainers)

Commits related to this issue

Most upvoted comments

@joostmeijles Can confirm this is a šŸ› on Next.js’s side, where we aren’t returning the correct revalidate period for non-prerendered route handler paths, causing it to return STALE.

I shared this with the team—hopefully we can get this <picture data-single-emoji=":fixed:" title=":fixed:">:fixed:</picture> soon!

Still broken with dynamic routes…hope they fix this eventually. One workaround at the moment is directly setting cache headers in the response. You’ll get a bit more control as well over revalidation and cache timing too:

return NextResponse.json(response, { status: 200, headers: { 'Cache-Control': 'public, s-maxage=60, stale-while-revalidate=120' } });

@joostmeijles Thanks for confirming. Will be looking to see why we’re getting STALE here!

@samcx tried with export const dynamic = 'force-static' (only), but it behaves the same for me. I get a MISS on first request and STALE on subsequent requests.

See https://github.com/joostmeijles/route-handler-stale/blob/main/app/items-force-static/[slug]/route.ts and https://routehandler-stale.vercel.app/items-force-static/a

First request image

Second request image

Please note that I see also STALE on your test URL: https://65814-route-handler-stale.vercel.app/items/a image

Running the examples in minimalMode (Vercel platform mode) results in the same x-next-cache-tags for the route and page examples.

Running https://github.com/joostmeijles/route-handler-stale/blob/main/app/items/[slug]/route.ts gives:

> node .\scripts\minimal-server.js C:\Repos\route-handler-stale items/a

'x-next-cache-tags' => {
      name: 'x-next-cache-tags',
      value: '_N_T_/layout,_N_T_/items/layout,_N_T_/items/[slug]/layout,_N_T_/items/[slug]/route,_N_T_/items/a'
}

Running https://github.com/joostmeijles/route-handler-stale/blob/main/app/items-page/[slug]/page.tsx gives:

> node .\scripts\minimal-server.js C:\Repos\route-handler-stale items-page/a

'x-next-cache-tags' => {
      name: 'x-next-cache-tags',
      value: '_N_T_/layout,_N_T_/items-page/layout,_N_T_/items-page/[slug]/layout,_N_T_/items-page/[slug]/page,_N_T_/items-page/a'
}

In addition, when running the examples locally the returned X-Nextjs-Cache header always correctly contains HIT for subsequent visits.

The issue is that the behaviour of route.ts and page.tsx is not the same. route.ts always returns STALE while it should return HIT on subsequent requests. This causes unnecessary function invocations on the origin server as the result can be cached (in the edge cache).

Pages handler (page.tsx)

The following page.tsx code

// page.tsx file
export default async function Page({ params }: { params: { slug: string } }) {
    return <span>{params.slug}</span>
}

export async function generateStaticParams() {
    return [];
}

returns upon visiting a slug, e.g. https://routehandler-stale.vercel.app/items-page/a

  • first visit: X-Vercel-Cache: MISS
  • subsequent visit: X-Vercel-Cache: HIT

Route handler (route.ts)

The following route.ts code

// route.ts file
export async function GET(
    request: Request,
    { params }: { params: { slug: string } }
) {
    const slug = params.slug
    return NextResponse.json({ slug })
}

export async function generateStaticParams() {
    return [];
}

returns upon visiting a slug, e.g. https://routehandler-stale.vercel.app/items/a

  • first visit: X-Vercel-Cache: STALE
  • subsequent visit: X-Vercel-Cache: STALE

This behavior is changing with Next.js 15 (where GET Route Handlers are not cached by default).

Would you might updating to the latest https://nextjs.org/blog/next-15-rc and retesting?