vercel/next.js · error

Warning: Custom Cache-Control headers detected for the follo

Error message

Warning: Custom Cache-Control headers detected for the following routes:
  - ${source}

Setting a custom Cache-Control header can break Next.js development behavior.

What it means

loadCustomRoutes scans header routes and warns when a custom Cache-Control header is set on a /_next/* source; such headers can break Next.js's own asset caching behavior (especially in development), so the offending route sources are listed for removal.

Source

Thrown at packages/next/src/lib/load-custom-routes.ts:745

        `redirects: ${redirects.length}\n` +
        `See more info: https://nextjs.org/docs/messages/max-custom-routes-reached`
    )
  }

  const cacheControlSources: string[] = []
  for (const headerRoute of headers) {
    if (!headerRoute.source.startsWith('/_next/')) {
      continue
    }
    for (const header of headerRoute.headers) {
      if (header.key.toLowerCase() === 'cache-control') {
        cacheControlSources.push(headerRoute.source)
        break
      }
    }
  }
  if (cacheControlSources.length > 0) {
    console.warn(
      bold(yellow(`Warning: `)) +
        `Custom Cache-Control headers detected for the following routes:\n` +
        cacheControlSources.map((source) => `  - ${source}`).join('\n') +
        `\n\nSetting a custom Cache-Control header can break Next.js development behavior.`
    )
  }

  if (config.deploymentId) {
    if (config.experimental?.useSkewCookie) {
      headers.unshift({
        source: '/:path*',
        headers: [
          {
            key: 'Set-Cookie',
            value: `__vdpl=${config.deploymentId}; Path=/; HttpOnly`,
          },
        ],
      })

View on GitHub (pinned to 0eb3775416)

Solutions

1. Remove custom Cache-Control headers for these routes in development, or scope them to production only.

When it happens

Trigger: Thrown at packages/next/src/lib/load-custom-routes.ts:745 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of vercel/next.js@0eb3775416 (2026-08-19). Data as JSON: /api/errors/45a2d9ef478b0350. Report an issue: GitHub.