facebook/react · error · Error

Symbols cannot be passed to a Server Function without a…

Error message

Symbols cannot be passed to a Server Function without a temporary reference set. Pass a TemporaryReferenceSet to the options.

What it means

Symbols have no wire representation in the Flight reply format, so a symbol argument can only be sent by registering it in a TemporaryReferenceSet that the server shares. If temporaryReferences is undefined (or the symbol is not reachable via a dedupe-able parent path), serializeReply throws, naming the missing option. The same constraint applies to symbol values anywhere in the argument tree, not just at the top level.

Solutions

  1. Pass a TemporaryReferenceSet in the encodeReply/callServer options so symbols can be registered and referenced by id
  2. Send a string instead: symbol.description or a stable registry key, and rebuild the symbol on the server from a shared table
  3. Audit argument trees for symbols before sending (typeof v === 'symbol') and map them explicitly
  4. If the symbol is only used as a property key locally, restructure to plain string keys for data that crosses the boundary

Example fix

// before
const THEMES = {dark: Symbol('dark'), light: Symbol('light')};
await setTheme(THEMES.dark); // throws

// after
await setTheme('dark'); // string token; server maps it back to its own symbol
Defensive patterns

Strategy: validation

Validate before calling

// Reject or map symbols before the call crosses the boundary
function assertNoBareSymbols(v: unknown, seen = new Set()): void {
  if (typeof v === 'symbol') {
    throw new Error('Symbol argument requires a TemporaryReferenceSet - or send a string token');
  }
  if (v === null || typeof v !== 'object' || seen.has(v)) return;
  seen.add(v);
  Object.values(v).forEach(c => assertNoBareSymbols(c, seen));
}

Type guard

const isSymbol = (v: unknown): v is symbol => typeof v === 'symbol';

Prevention

When it happens

Trigger: Passing a symbol as a Server Function argument or inside one: await setTheme(SYMBOLS.dark); library objects that internally use symbol keys/values (registries, well-known symbols) leaking into the payload without a temporaryReferences set.

Common situations: Sending theme/feature tokens implemented as symbols; styling libraries that key slots with symbols; enum-like symbols shared between client and server code; forgetting the options object entirely when hand-rolling encodeReply.

Related errors

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

Appendix: source

Thrown at packages/react-client/src/ReactFlightReplyClient.js:866

        'Client Functions cannot be passed directly to Server Functions. ' +
          'Only Functions passed from the Server can be passed back again.',
      );
    }

    if (typeof value === 'symbol') {
      if (temporaryReferences !== undefined && key.indexOf(':') === -1) {
        // TODO: If the property name contains a colon, we don't dedupe. Escape instead.
        const parentReference = writtenObjects.get(parent);
        if (parentReference !== undefined) {
          // If the parent has a reference, we can refer to this object indirectly
          // through the property name inside that parent.
          const reference = parentReference + ':' + key;
          // Store this object so that the server can refer to it later in responses.
          writeTemporaryReference(temporaryReferences, reference, value);
          return serializeTemporaryReferenceMarker();
        }
      }
      throw new Error(
        'Symbols cannot be passed to a Server Function without a ' +
          'temporary reference set. Pass a TemporaryReferenceSet to the options.' +
          (__DEV__ ? describeObjectForErrorMessage(parent, key) : ''),
      );
    }

    if (typeof value === 'bigint') {
      return serializeBigInt(value);
    }

    throw new Error(
      `Type ${typeof value} is not supported as an argument to a Server Function.`,
    );
  }

  function serializeModel(model: ReactServerValue, id: number): string {
    if (typeof model === 'object' && model !== null) {
      const reference = serializeByValueID(id);

View on GitHub (pinned to eafeac097b)