GitbookIO/gitbook · error · Error

Site space "${siteSpace.id}" not found in site structure

Error message

Site space "${siteSpace.id}" not found in site structure

What it means

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.

Source

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

        isLoggedInVisitor: ids.isLoggedInVisitor,
        displayAgentInstructions: ids.displayAgentInstructions,
        isAiAgent: ids.isAiAgent,
    };
}

/**
 * Create a site context scoped to a specific site space.
 * This keeps the site structure from the current context while resolving content
 * against the target space revision.
 */
export async function fetchSiteContextForSiteSpace(
    baseContext: GitBookSiteContext,
    siteSpace: SiteSpace
): Promise<GitBookSiteContext> {
    const found = findSiteSpaceBy(baseContext.structure, (entry) => entry.id === siteSpace.id);

    if (!found) {
        throw new Error(`Site space "${siteSpace.id}" not found in site structure`);
    }

    const spaceContext = await fetchSpaceContextByIds(baseContext, {
        space: siteSpace.space.id,
        shareKey: baseContext.shareKey,
        changeRequest: undefined,
        revision: siteSpace.space.revision,
    });

    const siteSpaces =
        baseContext.structure.type === 'siteSpaces'
            ? baseContext.structure.structure
            : (found.siteSection?.siteSpaces ?? baseContext.siteSpaces);

    const siteSpaceLinker = baseContext.linker.withOtherSiteSpace({
        spaceBasePath: getFallbackSiteSpacePath(baseContext, siteSpace),
    });

View on GitHub (pinned to db67585ee2)

Solutions

1. Re-fetch the site structure right before resolving the space so both come from the same snapshot (and pass matching cache tags/incremental revalidation)
2. Assert the SiteSpace object actually came from the same structure object you pass as baseContext
3. Log both the structure's space IDs and siteSpace.id at the failure site to spot drift immediately
4. If the space was deleted, surface a 404 to the caller instead of an unhandled error

Example fix

// before
const space = someExternallyProvidedSiteSpace;
const ctx = await fetchSiteContextForSiteSpace(baseContext, space);

// after
const space = baseContext.structure.type === 'siteSpaces'
    ? baseContext.structure.structure.find((s) => s.id === spaceId)
    : undefined;
if (!space) notFound();
const ctx = await fetchSiteContextForSiteSpace(baseContext, space);

const found = findSiteSpaceBy(baseContext.structure, (e) => e.id === siteSpace.id);
if (!found) notFound();

function isSiteSpaceInStructure(ctx: GitBookSiteContext, space: SiteSpace): boolean {
    return findSiteSpaceBy(ctx.structure, (e) => e.id === space.id) !== null;
}

try {
    const ctx = await fetchSiteContextForSiteSpace(baseContext, siteSpace);
} catch (e) {
    if (e instanceof Error && e.message.includes('not found in site structure')) notFound();
    throw e;
}

When it happens

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

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

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 "${ids.siteSpace}" not found in structure type="s

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