{"record":{"id":"d3d4a79b8f031c01","repo":"vercel/next.js","slug":"invalid-sample-defining-cookies-via-a-cookie-he","errorCode":null,"errorMessage":"Invalid sample: Defining cookies via a \"cookie\" header is not supported. Use `cookies: [{ name: ..., value: ... }]` instead.","messagePattern":"Invalid sample: Defining cookies via a \"cookie\" header is not supported\\. Use `cookies: \\[(.+?)\\]` instead\\.","errorType":"validation","errorClass":"InstantValidationError","httpStatus":null,"severity":"error","filePath":"packages/next/src/server/app-render/instant-validation/instant-samples.ts","lineNumber":174,"sourceCode":"  )\n}\n\n/**\n * Creates ReadonlyHeaders from sample header data.\n * Accessing a header not declared in the sample will throw an error.\n * Headers with `value: null` are declared (allowed to access) but return null.\n */\nexport function createHeadersFromSample(\n  rawSampleHeaders: InstantSample['headers'],\n  sampleCookies: InstantSample['cookies'],\n  route: string\n): ReadonlyHeaders {\n  // If we have cookie samples, add a `cookie` header to match.\n  // Accessing it will be implicitly allowed by the proxy --\n  // if the user defined some cookies, accessing the \"cookie\" header is also fine.\n  const sampleHeaders = rawSampleHeaders ? [...rawSampleHeaders] : []\n  if (sampleHeaders.find(([name]) => name.toLowerCase() === 'cookie')) {\n    throw new InstantValidationError(\n      'Invalid sample: Defining cookies via a \"cookie\" header is not supported. Use `cookies: [{ name: ..., value: ... }]` instead.'\n    )\n  }\n  if (sampleCookies) {\n    const cookieHeaderValue = sampleCookies.toString()\n    sampleHeaders.push([\n      'cookie',\n      // if the `cookies` samples were empty, or they were all `null`, then we have no cookies,\n      // and the header isn't present, but should remains readable, so we set it to null.\n      cookieHeaderValue !== '' ? cookieHeaderValue : null,\n    ])\n  }\n\n  const declaredNames = new Set<string>()\n  const headersInit: Record<string, string> = {}\n\n  for (const [name, value] of sampleHeaders) {\n    declaredNames.add(name.toLowerCase())","sourceCodeStart":156,"sourceCodeEnd":192,"githubUrl":"https://github.com/vercel/next.js/blob/0ae8c72462952df163f1b1e0726641bc5b40dc93/packages/next/src/server/app-render/instant-validation/instant-samples.ts#L156-L192","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove the 'cookie' entry from the sample's headers array.","Define cookies via the sample's cookies array: cookies: [{ name: 'session', value: '...' }].","The validator will automatically derive the cookie header from the cookies array.","For an absent cookie, use { name: 'x', value: null } in the cookies array."],"exampleFix":"// before\n// unstable_samples: {\n//   headers: [['cookie', 'session=abc']],\n// }\n\n// after\n// unstable_samples: {\n//   cookies: [{ name: 'session', value: 'abc' }],\n// }","handlingStrategy":"validation","validationCode":"// Validate sample config at author time.\nfunction validateSamples(headers: [string, string|null][]) {\n  const bad = headers.find(([n]) => n.toLowerCase() === 'cookie')\n  if (bad) throw new Error('Use cookies array, not a cookie header')\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always use the cookies array in samples, never a raw cookie header.","Review sample configs before enabling instant validation.","Use a lint/schema check for sample definitions.","Remember the validator auto-derives the cookie header from cookies."],"tags":["instant-validation","samples","cookies","headers","build"],"analyzedSha":"0ae8c72462952df163f1b1e0726641bc5b40dc93","analyzedAt":"2026-08-06T19:44:29.143Z","schemaVersion":2},"datasetVersion":"2026-08-07T02:17:10.218Z"}