facebook/react · error · Error

526

526

Error message

Could not reference an opaque temporary reference. This is likely due to misconfiguring the temporaryReferences options on the server.

What it means

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.

Source

Thrown at packages/react-server/src/ReactFlightReplyServer.js:1634

      case 'h': {
        // Server Reference
        const ref = value.slice(2);
        return getOutlinedModel(
          response,
          ref,
          obj,
          key,
          null,
          loadServerReference,
        );
      }
      case 'T': {
        // Temporary Reference
        if (
          reference === undefined ||
          response._temporaryReferences === undefined
        ) {
          throw new Error(
            'Could not reference an opaque temporary reference. ' +
              'This is likely due to misconfiguring the temporaryReferences options ' +
              'on the server.',
          );
        }
        return createTemporaryReference(
          response._temporaryReferences,
          reference,
        );
      }
      case 'Q': {
        // Map
        const ref = value.slice(2);
        return getOutlinedModel(response, ref, obj, key, null, createMap);
      }
      case 'W': {
        // Set
        const ref = value.slice(2);

View on GitHub (pinned to eafeac097b)

Solutions

1. Pass a fresh store when decoding: const args = await decodeReply(formData, {temporaryReferences: new WeakMap()}).
2. Thread that same store into any follow-up render/prerender call so decoded temp refs can be re-serialized.
3. Forward the original FormData (or busboy stream) untouched — never JSON round-trip it, which destroys File entries and key names.
4. Align versions of react, react-server, and react-server-dom-* so both sides of the boundary agree on the encoding.

Example fix

// before
const args = await decodeReply(formData);

// after
const temporaryReferences = new WeakMap();
const args = await decodeReply(formData, {temporaryReferences});

// Scan the raw reply for temporary reference rows before decoding.
function replyNeedsTemporaryReferences(formData: FormData): boolean {
  for (const value of formData.values()) {
    if (typeof value === 'string' && value.startsWith('$T')) return true;
  }
  return false;
}

let options = baseOptions;
if (replyNeedsTemporaryReferences(formData) && !options?.temporaryReferences) {
  options = {...options, temporaryReferences: new WeakMap()};
}

try {
  const args = await decodeReply(formData, options);
} catch (e) {
  if (e instanceof Error && e.message.includes('opaque temporary reference')) {
    return new Response('Malformed action payload', {status: 400});
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• 526
• 582
• 516
• Missing a temporary reference set but the RSC response retur
• React Element cannot be passed to Server Functions from the

AI-assisted analysis of facebook/react@eafeac097b (2026-08-21). Data as JSON: /api/errors/ba6d34d2caf70bfb. Report an issue: GitHub.