{"record":{"id":"a3eeb470b0718ed4","repo":"facebook/react","slug":"attempted-to-load-a-server-reference-outside-the-h","errorCode":null,"errorMessage":"Attempted to load a Server Reference outside the hosted root.","messagePattern":"Attempted to load a Server Reference outside the hosted root\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/react-server-dom-esm/src/client/ReactFlightClientConfigBundlerESM.js","lineNumber":74,"sourceCode":"  metadata: ClientReferenceMetadata,\n): ClientReference<T> {\n  const baseURL = bundlerConfig;\n  return {\n    specifier: baseURL + metadata[0],\n    name: metadata[1],\n  };\n}\n\nexport function resolveServerReference<T>(\n  config: ServerManifest,\n  id: ServerReferenceId,\n): ClientReference<T> {\n  const baseURL: string = config;\n  const idx = id.lastIndexOf('#');\n  const exportName = id.slice(idx + 1);\n  const fullURL = id.slice(0, idx);\n  if (!fullURL.startsWith(baseURL)) {\n    throw new Error(\n      'Attempted to load a Server Reference outside the hosted root.',\n    );\n  }\n  return {specifier: fullURL, name: exportName};\n}\n\nconst asyncModuleCache: Map<string, Thenable<any>> = new Map();\n\nexport function preloadModule<T>(\n  metadata: ClientReference<T>,\n): null | Thenable<any> {\n  const existingPromise = asyncModuleCache.get(metadata.specifier);\n  if (existingPromise) {\n    if (existingPromise.status === 'fulfilled') {\n      return null;\n    }\n    return existingPromise;\n  } else {","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/facebook/react/blob/eafeac097ba51e1eab809c07102126bd5f8e5425/packages/react-server-dom-esm/src/client/ReactFlightClientConfigBundlerESM.js#L56-L92","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Make the client's moduleBaseURL identical to the base URL the server used when rendering — derive both from one shared constant","Log the failing id (the part before the '#') and diff it against the configured base to see which side changed","Re-render the payload from a server whose baseURL matches the client configuration"],"exampleFix":"// before — server and client disagree on the root\n// server: renderToPipeableStream(<App/>, 'https://cdn.example.com/app/')\nconst data = createFromNodeStream(stream, '/app', 'file:///workspace/app/');\n\n// after — one shared constant on both sides\n// shared/config.js\nexport const MODULE_BASE = 'https://cdn.example.com/app/';\nconst data = createFromNodeStream(stream, '/app', MODULE_BASE);","handlingStrategy":"validation","validationCode":"export function isResolvableServerReference(id, baseURL) {\n  const idx = id.lastIndexOf('#');\n  return idx > 0 && id.slice(0, idx).startsWith(baseURL);\n}\n// before consuming a payload, check every action id you intend to call:\nif (!isResolvableServerReference(id, MODULE_BASE)) throw new Error('root mismatch: ' + id);","typeGuard":"export function parseServerReference(ref, baseURL) {\n  const idx = ref.lastIndexOf('#');\n  if (idx <= 0) return null;\n  const fullURL = ref.slice(0, idx);\n  return fullURL.startsWith(baseURL) ? {fullURL, name: ref.slice(idx + 1)} : null;\n}","tryCatchPattern":null,"preventionTips":["Define the module base once (shared config module) and use it on both server render and client createFrom*","Validate the base URL at boot in every environment","Log the raw reference id when resolution fails to catch drift early"],"tags":["react-server-components","server-actions","base-url","rsc-client"],"backgroundTag":"rsc-base-url-mismatch","analyzedSha":"eafeac097ba51e1eab809c07102126bd5f8e5425","analyzedAt":"2026-08-21T22:01:08.818Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}