GitbookIO/gitbook · error · Error

Site space "${ids.siteSpace}" not found in structure type="s

Error message

Site space "${ids.siteSpace}" not found in structure type="siteSpaces"

What it means

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.

Source

Thrown at packages/gitbook/src/lib/context.ts:346

    const sections = ids.siteSection
        ? parseSiteSectionsAndGroups(siteStructure, ids.siteSection)
        : null;
    const visibleSections = ids.siteSection
        ? parseVisibleSiteSectionsAndGroups(siteStructure, ids.siteSection)
        : null;

    // Parse the current siteSpace and siteSpaces based on the site structure type.
    const {
        siteSpaces,
        siteSpace,
        visibleSiteSpaces,
    }: { siteSpaces: SiteSpace[]; siteSpace: SiteSpace; visibleSiteSpaces: SiteSpace[] } = (() => {
        if (siteStructure.type === 'siteSpaces') {
            const siteSpaces = siteStructure.structure;
            const siteSpace = siteSpaces.find((siteSpace) => siteSpace.id === ids.siteSpace);

            if (!siteSpace) {
                throw new Error(
                    `Site space "${ids.siteSpace}" not found in structure type="siteSpaces"`
                );
            }

            return { siteSpaces, siteSpace, visibleSiteSpaces: filterHiddenSiteSpaces(siteSpaces) };
        }

        if (siteStructure.type === 'sections') {
            assert(
                sections,
                `cannot find site space "${ids.siteSpace}" because parsed sections are missing siteStructure.type="sections" siteSection="${ids.siteSection}"`
            );

            const currentSection = sections.current;
            const siteSpaces = currentSection.siteSpaces;
            const siteSpace = currentSection.siteSpaces.find(
                (siteSpace) => siteSpace.id === ids.siteSpace
            );

View on GitHub (pinned to db67585ee2)

Solutions

1. Verify the siteSpace ID in the failing URL against the current site structure (fetch the structure and list site space IDs)
2. If the space moved, update the link to the new site space path or fall back to the site root
3. Clear stale caches (ISR/cache tags) if the structure changed recently so the freshest structure is used
4. Return a proper 404 page to the visitor instead of letting the error bubble, since this is an not-found condition

Example fix

// before
const ctx = await fetchSiteContextByIds(siteData, ids);

// after
let ctx;
try {
    ctx = await fetchSiteContextByIds(siteData, ids);
} catch (e) {
    if (e instanceof Error && e.message.includes('not found in structure type="siteSpaces"')) {
        notFound(); // render 404
    }
    throw e;
}

const structure = siteData.structure;
const exists = structure.type === 'siteSpaces' &&
    structure.structure.some((s) => s.id === ids.siteSpace);

function siteSpaceExists(structure: SiteStructure, id?: string): boolean {
    if (structure.type === 'siteSpaces') {
        return structure.structure.some((s) => s.id === id);
    }
    if (structure.type === 'sections') {
        return structure.structure.some((section) =>
            section.siteSpaces.some((s) => s.id === id)
        );
    }
    return false;
}

try {
    const ctx = await fetchSiteContextByIds(siteData, ids);
} catch (e) {
    if (e instanceof Error && e.message.includes('not found in structure')) notFound();
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Site space "${ids.siteSpace}" not found in structure type="s
• Site space "${siteSpace.id}" not found in site structure

AI-assisted analysis of GitbookIO/gitbook@db67585ee2 (2026-08-28). Data as JSON: /api/errors/a42fcb6107afd098. Report an issue: GitHub.