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

The serialization-side mirror of the reply error with the same text: the model being rendered contains a value created by createTemporaryReference (an opaque one-request handle, e.g. a File or client-held value from a decoded action reply), but the current render request was not configured with a temporaryReferences store. Without the store the serializer cannot map the wrapper back to its id, so it refuses rather than emit an unresolvable value.

Source

Thrown at packages/react-server/src/ReactFlightServer.js:4261

    if (request.temporaryReferences !== undefined) {
      const tempRef = resolveTemporaryReference(
        request.temporaryReferences,
        value,
      );
      if (tempRef !== undefined) {
        return serializeTemporaryReference(request, tempRef);
      }
    }

    if (enableTaint) {
      const tainted = TaintRegistryObjects.get(value);
      if (tainted !== undefined) {
        throwTaintViolation(tainted);
      }
    }

    if (isOpaqueTemporaryReference(value)) {
      throw new Error(
        'Could not reference an opaque temporary reference. ' +
          'This is likely due to misconfiguring the temporaryReferences options ' +
          'on the server.',
      );
    } else if (/^on[A-Z]/.test(parentPropertyName)) {
      throw new Error(
        'Event handlers cannot be passed to Client Component props.' +
          describeObjectForErrorMessage(parent, parentPropertyName) +
          '\nIf you need interactivity, consider converting part of this to a Client Component.',
      );
    } else if (
      __DEV__ &&
      (jsxChildrenParents.has(parent) ||
        (jsxPropsParents.has(parent) && parentPropertyName === 'children'))
    ) {
      const componentName = value.displayName || value.name || 'Component';
      throw new Error(
        'Functions are not valid as a child of Client Components. This may happen if ' +

View on GitHub (pinned to eafeac097b)

Solutions

Pass the same temporaryReferences store you gave decodeReply as an option to render/prerender.
If the value must outlive the request, materialize it first (read the File, persist the data) and pass the result.
Audit custom request-creation code to forward the temporaryReferences option end to end.

Example fix

// before
const temporaryReferences = new WeakMap();
const args = await decodeReply(formData, {temporaryReferences});
const {stream} = render(<App actionArgs={args} />, manifest);

// after
const temporaryReferences = new WeakMap();
const args = await decodeReply(formData, {temporaryReferences});
const {stream} = render(<App actionArgs={args} />, manifest, {temporaryReferences});

Defensive patterns

Strategy: validation

Validate before calling

// Identity check against the decode store — Map.has never touches the proxy.
export function argsContainTemporaryReferences(
  args: unknown[],
  temporaryReferences: WeakMap<object, string>,
): boolean {
  return args.some(a => typeof a === 'object' && a !== null && temporaryReferences.has(a));
}

if (argsContainTemporaryReferences(args, temporaryReferences)) {
  render(tree, manifest, {...opts, temporaryReferences});
}

Type guard

export function isTemporaryReference(v: unknown, store: WeakMap<object, string>): boolean {
  return typeof v === 'object' && v !== null && store.has(v);
}

Try / catch

try {
  render(tree, manifest, opts);
} catch (e) {
  if (String((e as Error)?.message).includes('opaque temporary reference')) {
    return failRequest('temporary references were not threaded into this render');
  }
  throw e;
}

Prevention

Create the temporaryReferences store once per request and pass it to both decodeReply and render/prerender.
Materialize temp-ref values (e.g. read uploaded files) when they must outlive the request.

When it happens

Trigger: Calling render()/prerender() on a tree that includes a temporary reference obtained from decodeReply(..., {temporaryReferences}) while the render options omit temporaryReferences; forwarding decoded action args into a follow-up server render without threading the same store.

Common situations: Re-rendering after a server action in a custom framework that builds a new request per render; passing decoded action arguments (which contain File handles) into optimistic-UI re-renders; partial adoption of the temporaryReferences API.

Related errors

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