facebook/react · error · Error

Attempted to load a Server Reference outside the hosted root

Error message

Attempted to load a Server Reference outside the hosted root.

What it means

In react-server-dom-esm's client, a serialized Server Reference id has the form <fullURL>#<exportName>. resolveServerReference verifies that fullURL starts with the moduleBaseURL you passed to createFromNodeStream(stream, moduleRootPath, moduleBaseURL), because that prefix is what lets the client map the id onto modules under its hosted root. If the check fails, the payload was produced under a different module root than the client is configured for.

Source

Thrown at packages/react-server-dom-esm/src/client/ReactFlightClientConfigBundlerESM.js:74

  metadata: ClientReferenceMetadata,
): ClientReference<T> {
  const baseURL = bundlerConfig;
  return {
    specifier: baseURL + metadata[0],
    name: metadata[1],
  };
}

export function resolveServerReference<T>(
  config: ServerManifest,
  id: ServerReferenceId,
): ClientReference<T> {
  const baseURL: string = config;
  const idx = id.lastIndexOf('#');
  const exportName = id.slice(idx + 1);
  const fullURL = id.slice(0, idx);
  if (!fullURL.startsWith(baseURL)) {
    throw new Error(
      'Attempted to load a Server Reference outside the hosted root.',
    );
  }
  return {specifier: fullURL, name: exportName};
}

const asyncModuleCache: Map<string, Thenable<any>> = new Map();

export function preloadModule<T>(
  metadata: ClientReference<T>,
): null | Thenable<any> {
  const existingPromise = asyncModuleCache.get(metadata.specifier);
  if (existingPromise) {
    if (existingPromise.status === 'fulfilled') {
      return null;
    }
    return existingPromise;
  } else {

View on GitHub (pinned to eafeac097b)

Solutions

1. Make the client's moduleBaseURL identical to the base URL the server used when rendering — derive both from one shared constant
2. Log the failing id (the part before the '#') and diff it against the configured base to see which side changed
3. Re-render the payload from a server whose baseURL matches the client configuration

Example fix

// before — server and client disagree on the root
// server: renderToPipeableStream(<App/>, 'https://cdn.example.com/app/')
const data = createFromNodeStream(stream, '/app', 'file:///workspace/app/');

// after — one shared constant on both sides
// shared/config.js
export const MODULE_BASE = 'https://cdn.example.com/app/';
const data = createFromNodeStream(stream, '/app', MODULE_BASE);

export function isResolvableServerReference(id, baseURL) {
  const idx = id.lastIndexOf('#');
  return idx > 0 && id.slice(0, idx).startsWith(baseURL);
}
// before consuming a payload, check every action id you intend to call:
if (!isResolvableServerReference(id, MODULE_BASE)) throw new Error('root mismatch: ' + id);

export function parseServerReference(ref, baseURL) {
  const idx = ref.lastIndexOf('#');
  if (idx <= 0) return null;
  const fullURL = ref.slice(0, idx);
  return fullURL.startsWith(baseURL) ? {fullURL, name: ref.slice(idx + 1)} : null;
}

When it happens

Trigger: createFromNodeStream is called with a moduleBaseURL that does not prefix the server-reference ids embedded in the Flight payload — the server rendered with a different baseURL config (different host, mount path, or file root), so id.slice(0, idx).startsWith(baseURL) is false.

Common situations: Server rendered with file:// workspace URLs while the client uses an https base (or vice versa); app moved to a new mount path; payload produced in one environment and consumed in another.

Related errors

• Server Functions cannot be called during initial render. Thi
• Attempted to load a Client Module outside the hosted root.
• Invalid server action: ${ref}
• No server callback has been registered. Call setServerCallba
• Server Functions cannot be called during initial render. Thi

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