{"record":{"id":"a42fcb6107afd098","repo":"GitbookIO/gitbook","slug":"site-space-ids-sitespace-not-found-in-structu","errorCode":null,"errorMessage":"Site space \"${ids.siteSpace}\" not found in structure type=\"siteSpaces\"","messagePattern":"Site space \"(.+?)\" not found in structure type=\"siteSpaces\"","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/gitbook/src/lib/context.ts","lineNumber":346,"sourceCode":"    const sections = ids.siteSection\n        ? parseSiteSectionsAndGroups(siteStructure, ids.siteSection)\n        : null;\n    const visibleSections = ids.siteSection\n        ? parseVisibleSiteSectionsAndGroups(siteStructure, ids.siteSection)\n        : null;\n\n    // Parse the current siteSpace and siteSpaces based on the site structure type.\n    const {\n        siteSpaces,\n        siteSpace,\n        visibleSiteSpaces,\n    }: { siteSpaces: SiteSpace[]; siteSpace: SiteSpace; visibleSiteSpaces: SiteSpace[] } = (() => {\n        if (siteStructure.type === 'siteSpaces') {\n            const siteSpaces = siteStructure.structure;\n            const siteSpace = siteSpaces.find((siteSpace) => siteSpace.id === ids.siteSpace);\n\n            if (!siteSpace) {\n                throw new Error(\n                    `Site space \"${ids.siteSpace}\" not found in structure type=\"siteSpaces\"`\n                );\n            }\n\n            return { siteSpaces, siteSpace, visibleSiteSpaces: filterHiddenSiteSpaces(siteSpaces) };\n        }\n\n        if (siteStructure.type === 'sections') {\n            assert(\n                sections,\n                `cannot find site space \"${ids.siteSpace}\" because parsed sections are missing siteStructure.type=\"sections\" siteSection=\"${ids.siteSection}\"`\n            );\n\n            const currentSection = sections.current;\n            const siteSpaces = currentSection.siteSpaces;\n            const siteSpace = currentSection.siteSpaces.find(\n                (siteSpace) => siteSpace.id === ids.siteSpace\n            );","sourceCodeStart":328,"sourceCodeEnd":364,"githubUrl":"https://github.com/GitbookIO/gitbook/blob/db67585ee243d063c459a855988f21612cea9c95/packages/gitbook/src/lib/context.ts#L328-L364","documentation":"Thrown by fetchSiteContextByIds when resolving a site whose structure is of type 'siteSpaces': the requested siteSpace ID (ids.siteSpace) does not match any site space in the structure returned by the API. It indicates a mismatch between the URL/handoff IDs and the actual site structure — effectively a 404 for that site space.","triggerScenarios":"Requesting a page under /s/<site>/<siteSpace>/... (or calling fetchSiteContextByURLLookup with an explicit siteSpace ID) where that ID is not present in the siteSpaces array of the site structure — deleted site space, stale link, or a typo in the ID.","commonSituations":"A site space was deleted or renamed upstream but cached links/URLs still reference it; content was reorganized between when the URL was generated and when it was requested; hardcoded siteSpace IDs in integration tests or embeds drifting out of date.","solutions":["Verify the siteSpace ID in the failing URL against the current site structure (fetch the structure and list site space IDs)","If the space moved, update the link to the new site space path or fall back to the site root","Clear stale caches (ISR/cache tags) if the structure changed recently so the freshest structure is used","Return a proper 404 page to the visitor instead of letting the error bubble, since this is an not-found condition"],"exampleFix":"// before\nconst ctx = await fetchSiteContextByIds(siteData, ids);\n\n// after\nlet ctx;\ntry {\n    ctx = await fetchSiteContextByIds(siteData, ids);\n} catch (e) {\n    if (e instanceof Error && e.message.includes('not found in structure type=\"siteSpaces\"')) {\n        notFound(); // render 404\n    }\n    throw e;\n}","handlingStrategy":"validation","validationCode":"const structure = siteData.structure;\nconst exists = structure.type === 'siteSpaces' &&\n    structure.structure.some((s) => s.id === ids.siteSpace);","typeGuard":"function siteSpaceExists(structure: SiteStructure, id?: string): boolean {\n    if (structure.type === 'siteSpaces') {\n        return structure.structure.some((s) => s.id === id);\n    }\n    if (structure.type === 'sections') {\n        return structure.structure.some((section) =>\n            section.siteSpaces.some((s) => s.id === id)\n        );\n    }\n    return false;\n}","tryCatchPattern":"try {\n    const ctx = await fetchSiteContextByIds(siteData, ids);\n} catch (e) {\n    if (e instanceof Error && e.message.includes('not found in structure')) notFound();\n    throw e;\n}","preventionTips":["Resolve site spaces by ID from a freshly fetched structure rather than trusting URL-derived IDs","Keep a redirect map when site spaces are renamed or deleted","Wrap context resolution in an error boundary that renders 404 for not-found structure errors"],"tags":["site-structure","site-space","not-found","routing"],"backgroundTag":"resource-not-found","analyzedSha":"db67585ee243d063c459a855988f21612cea9c95","analyzedAt":"2026-08-28T17:49:47.831Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}