vercel/next.js · error · InstantValidationError

Invalid sample: Defining cookies via a "cookie" header is no

Error message

Invalid sample: Defining cookies via a "cookie" header is not supported. Use `cookies: [{ name: ..., value: ... }]` instead.

What it means

An InstantValidationError raised during build-time 'instant' validation when a route's unstable_samples configuration defines a 'cookie' header. Because cookies have a dedicated sample mechanism (the cookies array), the validator rejects samples that try to set the raw 'cookie' HTTP header, which would conflict with the derived cookie header.

Source

Thrown at packages/next/src/server/app-render/instant-validation/instant-samples.ts:174

  )
}

/**
 * Creates ReadonlyHeaders from sample header data.
 * Accessing a header not declared in the sample will throw an error.
 * Headers with `value: null` are declared (allowed to access) but return null.
 */
export function createHeadersFromSample(
  rawSampleHeaders: InstantSample['headers'],
  sampleCookies: InstantSample['cookies'],
  route: string
): ReadonlyHeaders {
  // If we have cookie samples, add a `cookie` header to match.
  // Accessing it will be implicitly allowed by the proxy --
  // if the user defined some cookies, accessing the "cookie" header is also fine.
  const sampleHeaders = rawSampleHeaders ? [...rawSampleHeaders] : []
  if (sampleHeaders.find(([name]) => name.toLowerCase() === 'cookie')) {
    throw new InstantValidationError(
      'Invalid sample: Defining cookies via a "cookie" header is not supported. Use `cookies: [{ name: ..., value: ... }]` instead.'
    )
  }
  if (sampleCookies) {
    const cookieHeaderValue = sampleCookies.toString()
    sampleHeaders.push([
      'cookie',
      // if the `cookies` samples were empty, or they were all `null`, then we have no cookies,
      // and the header isn't present, but should remains readable, so we set it to null.
      cookieHeaderValue !== '' ? cookieHeaderValue : null,
    ])
  }

  const declaredNames = new Set<string>()
  const headersInit: Record<string, string> = {}

  for (const [name, value] of sampleHeaders) {
    declaredNames.add(name.toLowerCase())

View on GitHub (pinned to 0ae8c72462)

Solutions

1. Remove the 'cookie' entry from the sample's headers array.
2. Define cookies via the sample's cookies array: cookies: [{ name: 'session', value: '...' }].
3. The validator will automatically derive the cookie header from the cookies array.
4. For an absent cookie, use { name: 'x', value: null } in the cookies array.

Example fix

// before
// unstable_samples: {
//   headers: [['cookie', 'session=abc']],
// }

// after
// unstable_samples: {
//   cookies: [{ name: 'session', value: 'abc' }],
// }

// Validate sample config at author time.
function validateSamples(headers: [string, string|null][]) {
  const bad = headers.find(([n]) => n.toLowerCase() === 'cookie')
  if (bad) throw new Error('Use cookies array, not a cookie header')
}

When it happens

Trigger: During instant validation, createHeadersFromSample() inspects sampleHeaders; if any entry's name (lowercased) equals 'cookie', it throws. This happens when a developer writes headers: [['cookie', '...']] in the sample config instead of using the cookies array.

Common situations: Migrating to the instant validation feature and naively copying request headers (including cookie) into the sample; misunderstanding the samples API; copying a curl request's headers wholesale into a sample.

Related errors

• Expected sample param value for segment '${rawSegment}' to b
• Expected sample param value for segment '${rawSegment}' to b
• Draft mode cannot be enabled during build-time instant valid
• Draft mode cannot be disabled during build-time instant vali
• Command failed: ${command} ${args.join(' ')} (exit ${code})

AI-assisted analysis of vercel/next.js@0ae8c72462 (2026-08-06). Data as JSON: /api/errors/d3d4a79b8f031c01. Report an issue: GitHub.