{"record":{"id":"ba6d34d2caf70bfb","repo":"facebook/react","slug":"526","errorCode":"526","errorMessage":"Could not reference an opaque temporary reference. This is likely due to misconfiguring the temporaryReferences options on the server.","messagePattern":"Could not reference an opaque temporary reference\\. This is likely due to misconfiguring the temporaryReferences options on the server\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/react-server/src/ReactFlightReplyServer.js","lineNumber":1634,"sourceCode":"      case 'h': {\n        // Server Reference\n        const ref = value.slice(2);\n        return getOutlinedModel(\n          response,\n          ref,\n          obj,\n          key,\n          null,\n          loadServerReference,\n        );\n      }\n      case 'T': {\n        // Temporary Reference\n        if (\n          reference === undefined ||\n          response._temporaryReferences === undefined\n        ) {\n          throw new Error(\n            'Could not reference an opaque temporary reference. ' +\n              'This is likely due to misconfiguring the temporaryReferences options ' +\n              'on the server.',\n          );\n        }\n        return createTemporaryReference(\n          response._temporaryReferences,\n          reference,\n        );\n      }\n      case 'Q': {\n        // Map\n        const ref = value.slice(2);\n        return getOutlinedModel(response, ref, obj, key, null, createMap);\n      }\n      case 'W': {\n        // Set\n        const ref = value.slice(2);","sourceCodeStart":1616,"sourceCodeEnd":1652,"githubUrl":"https://github.com/facebook/react/blob/eafeac097ba51e1eab809c07102126bd5f8e5425/packages/react-server/src/ReactFlightReplyServer.js#L1616-L1652","documentation":"Thrown while a server decodes a client reply (server action arguments) that contains a 'T' row — an encoded temporary reference. Temporary references are opaque one-request handles (typically File/Blob values collected from a form) that only exist when the caller passes a temporaryReferences store into decodeReply/decodeReplyFromBusboy. The decoder refuses to materialize the reference when the id is missing or when response._temporaryReferences was never configured, because the value cannot be reconstructed safely without the store.","triggerScenarios":"Calling decodeReply(formData) or decodeReplyFromBusboy on a payload containing a $T row without passing {temporaryReferences} in the options; a custom reply transport that rewrites or drops the '$K'/'t_' keys so the reference id lookup returns undefined; version skew where the runtime that encoded the reply expects the store but the decoding side was never given one.","commonSituations":"Form actions with file uploads (progressive enhancement) where a framework wrapper forgets to create the temporaryReferences Map; hand-rolled action handlers that rebuild FormData from JSON; mixing react and react-server-dom-* versions that disagree on the temporary reference encoding.","solutions":["Pass a fresh store when decoding: const args = await decodeReply(formData, {temporaryReferences: new WeakMap()}).","Thread that same store into any follow-up render/prerender call so decoded temp refs can be re-serialized.","Forward the original FormData (or busboy stream) untouched — never JSON round-trip it, which destroys File entries and key names.","Align versions of react, react-server, and react-server-dom-* so both sides of the boundary agree on the encoding."],"exampleFix":"// before\nconst args = await decodeReply(formData);\n\n// after\nconst temporaryReferences = new WeakMap();\nconst args = await decodeReply(formData, {temporaryReferences});","handlingStrategy":"validation","validationCode":"// Scan the raw reply for temporary reference rows before decoding.\nfunction replyNeedsTemporaryReferences(formData: FormData): boolean {\n  for (const value of formData.values()) {\n    if (typeof value === 'string' && value.startsWith('$T')) return true;\n  }\n  return false;\n}\n\nlet options = baseOptions;\nif (replyNeedsTemporaryReferences(formData) && !options?.temporaryReferences) {\n  options = {...options, temporaryReferences: new WeakMap()};\n}","typeGuard":null,"tryCatchPattern":"try {\n  const args = await decodeReply(formData, options);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('opaque temporary reference')) {\n    return new Response('Malformed action payload', {status: 400});\n  }\n  throw e;\n}","preventionTips":["Create the temporaryReferences store next to every decodeReply call and reuse it for any subsequent render.","Never rebuild action FormData by hand; forward the request body as-is.","Keep react and react-server-dom-* versions in lockstep."],"tags":["server-components","server-actions","temporary-references","serialization","form-data"],"backgroundTag":"rsc-temporary-references","analyzedSha":"eafeac097ba51e1eab809c07102126bd5f8e5425","analyzedAt":"2026-08-21T22:01:08.818Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}