{"record":{"id":"ba8d615474f11417","repo":"GitbookIO/gitbook","slug":"site-space-sitespace-id-not-found-in-site-str","errorCode":null,"errorMessage":"Site space \"${siteSpace.id}\" not found in site structure","messagePattern":"Site space \"(.+?)\" not found in site structure","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/gitbook/src/lib/context.ts","lineNumber":456,"sourceCode":"        isLoggedInVisitor: ids.isLoggedInVisitor,\n        displayAgentInstructions: ids.displayAgentInstructions,\n        isAiAgent: ids.isAiAgent,\n    };\n}\n\n/**\n * Create a site context scoped to a specific site space.\n * This keeps the site structure from the current context while resolving content\n * against the target space revision.\n */\nexport async function fetchSiteContextForSiteSpace(\n    baseContext: GitBookSiteContext,\n    siteSpace: SiteSpace\n): Promise<GitBookSiteContext> {\n    const found = findSiteSpaceBy(baseContext.structure, (entry) => entry.id === siteSpace.id);\n\n    if (!found) {\n        throw new Error(`Site space \"${siteSpace.id}\" not found in site structure`);\n    }\n\n    const spaceContext = await fetchSpaceContextByIds(baseContext, {\n        space: siteSpace.space.id,\n        shareKey: baseContext.shareKey,\n        changeRequest: undefined,\n        revision: siteSpace.space.revision,\n    });\n\n    const siteSpaces =\n        baseContext.structure.type === 'siteSpaces'\n            ? baseContext.structure.structure\n            : (found.siteSection?.siteSpaces ?? baseContext.siteSpaces);\n\n    const siteSpaceLinker = baseContext.linker.withOtherSiteSpace({\n        spaceBasePath: getFallbackSiteSpacePath(baseContext, siteSpace),\n    });\n","sourceCodeStart":438,"sourceCodeEnd":474,"githubUrl":"https://github.com/GitbookIO/gitbook/blob/db67585ee243d063c459a855988f21612cea9c95/packages/gitbook/src/lib/context.ts#L438-L474","documentation":"Thrown by fetchSiteContextForSiteSpace when a SiteSpace object you hand it cannot be found by ID anywhere in the baseContext.structure (via findSiteSpaceBy). This happens when the SiteSpace payload and the site structure come from different sources or points in time and disagree.","triggerScenarios":"Calling siteSpaceContext (or fetchSiteContextForSiteSpace directly) with a SiteSpace whose id is not present in baseContext.structure — e.g. the structure was fetched before the space was created, a stale cached structure, or a SiteSpace object constructed with a wrong/fabricated id.","commonSituations":"Race between site structure fetch and site space fetch (space created/deleted in between); mixing a space object from one site with the structure of another; long-lived cached baseContext in a serverless deployment serving outdated structures.","solutions":["Re-fetch the site structure right before resolving the space so both come from the same snapshot (and pass matching cache tags/incremental revalidation)","Assert the SiteSpace object actually came from the same structure object you pass as baseContext","Log both the structure's space IDs and siteSpace.id at the failure site to spot drift immediately","If the space was deleted, surface a 404 to the caller instead of an unhandled error"],"exampleFix":"// before\nconst space = someExternallyProvidedSiteSpace;\nconst ctx = await fetchSiteContextForSiteSpace(baseContext, space);\n\n// after\nconst space = baseContext.structure.type === 'siteSpaces'\n    ? baseContext.structure.structure.find((s) => s.id === spaceId)\n    : undefined;\nif (!space) notFound();\nconst ctx = await fetchSiteContextForSiteSpace(baseContext, space);","handlingStrategy":"type-guard","validationCode":"const found = findSiteSpaceBy(baseContext.structure, (e) => e.id === siteSpace.id);\nif (!found) notFound();","typeGuard":"function isSiteSpaceInStructure(ctx: GitBookSiteContext, space: SiteSpace): boolean {\n    return findSiteSpaceBy(ctx.structure, (e) => e.id === space.id) !== null;\n}","tryCatchPattern":"try {\n    const ctx = await fetchSiteContextForSiteSpace(baseContext, siteSpace);\n} catch (e) {\n    if (e instanceof Error && e.message.includes('not found in site structure')) notFound();\n    throw e;\n}","preventionTips":["Always derive SiteSpace objects from the same structure object used as baseContext","Revalidate the structure cache (via cache tags) whenever site spaces are mutated","Never construct SiteSpace objects with hardcoded IDs in production paths"],"tags":["site-structure","site-space","cache-invalidation","not-found"],"backgroundTag":"resource-not-found","analyzedSha":"db67585ee243d063c459a855988f21612cea9c95","analyzedAt":"2026-08-28T17:49:47.831Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}