facebook/react · error · Error

Invalid reference.

Error message

Invalid reference.

What it means

While parsing an RSC/Flight payload, inline references are written as $<id>.<path>.<to>.<field>. The client resolves them by walking that path over the already-parsed chunk with id. If at any step the current value is not an object that owns the next key in the path (a primitive, missing property, null), the walk cannot continue and the client throws 'Invalid reference.' - the payload's reference points somewhere that does not exist.

Source

Thrown at packages/react-client/src/ReactFlightClient.js:1715

              rejectReference(
                response,
                reference.handler,
                referencedChunk.reason,
              );
              return;
            }
          }
        }
      }
      const name = path[i];
      if (
        typeof value === 'object' &&
        value !== null &&
        hasOwnProperty.call(value, name)
      ) {
        value = value[name];
      } else {
        throw new Error('Invalid reference.');
      }
    }

    while (
      typeof value === 'object' &&
      value !== null &&
      value.$$typeof === REACT_LAZY_TYPE
    ) {
      // If what we're referencing is a Lazy it must be because we inserted one as a virtual node
      // while it was blocked by other data. If it's no longer blocked, we can unwrap it.
      const referencedChunk: SomeChunk<any> = value._payload;
      if (referencedChunk === handler.chunk) {
        // This is a reference to the thing we're currently blocking. We can peak
        // inside of it to get the value.
        value = handler.value;
        continue;
      } else {
        switch (referencedChunk.status) {

View on GitHub (pinned to eafeac097b)

Solutions

1. Make react, react-dom, and react-server-dom-* package versions match exactly on server and client, and deploy both from the same build
2. Log the raw Flight rows around the failure (tee the stream) to find the $id.path that cannot resolve, then check what the server actually emitted for that id
3. If you emit custom references, verify the referenced object really contains each key in the path at serialization time
4. Rule out stream corruption: bypass proxies/edge transforms, disable payload caching, and retry a fresh request

Example fix

// before: server and client resolved different builds
// package.json (web): react-server-dom-webpack@canary-a
// package.json (server): react-server-dom-webpack@canary-b

// after: single source of truth
// package.json (workspace root): react-server-dom-webpack pinned to one exact canary,
// consumed by both server and client builds in the same CI artifact

try {
  const root = await createFromFetch(fetch(url, {headers: {accept: 'text/x-component'}}));
} catch (e) {
  if (e instanceof Error && e.message === 'Invalid reference.') {
    // Corrupt or version-skewed RSC payload: verify server/client React versions,
    // bust caches, and refetch a fresh payload rather than retrying blindly
    await refetchFreshPayload();
  } else throw e;
}

When it happens

Trigger: The server serialized $1.user.name but the model for $1 has no 'user' key, or 'user' resolved to a primitive; payloads produced by mismatched react-server-dom versions on either side; a Flight stream truncated or rewritten by a proxy so an out-of-order reference arrives pointing at a different shape; hand-crafted or mutated rows in custom transports.

Common situations: Deploying server and client bundles from different builds (version skew) so row shapes differ; middleware/CDN transformations corrupting the stream; custom servers that cache or stitch RSC payloads incorrectly; a desync between what the server exported and what a reference path assumes.

Related errors

• Missing a temporary reference set but the RSC response retur
• Values cannot be passed to next() of AsyncIterables passed t
• Failed to read a RSC payload created by a development versio
• Type ${typeof value} is not supported as an argument to a Se
• Trying to call a function from "use server" but the callServ

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