GitbookIO/gitbook · error · Error

GitBook client not initialized. Call GitBook("init", { siteU

Error message

GitBook client not initialized. Call GitBook("init", { siteURL: "..." }) first.

What it means

Thrown by the internal getClient() in @gitbook/embed's standalone bundle when an API is invoked before GitBook('init', ...) has run. The standalone script stores a module-level _client created during 'init'; any other command that needs the client dereferences it and fails if init was skipped or not run yet.

Source

Thrown at packages/embed/src/standalone/index.ts:132

    document.body.appendChild(probe);
    const used = getComputedStyle(probe).color;
    probe.remove();

    return used === 'rgb(255, 255, 255)' ? 'dark' : 'light';
}

/** Mirror the resolved scheme onto the widget's own chrome, and hand it back for the frame's URL. */
function applyColorScheme(): 'light' | 'dark' {
    const colorScheme = resolveColorScheme();
    for (const element of [widgetButton, widgetWindow]) {
        element.dataset.colorScheme = colorScheme;
    }
    return colorScheme;
}

function getClient() {
    if (!_client) {
        throw new Error(
            'GitBook client not initialized. Call GitBook("init", { siteURL: "..." }) first.'
        );
    }
    return _client;
}

function getIframe() {
    if (!widgetIframe || !_frame) {
        const client = getClient();

        widgetIframe?.remove();
        widgetIframe = document.createElement('iframe');
        widgetIframe.id = 'gitbook-widget-iframe';
        widgetIframe.allow = 'clipboard-write';
        // One read for both, so the docs can't come back in a different scheme than the panel.
        widgetIframe.src = client.getFrameURL({ ...frameOptions, colorScheme: applyColorScheme() });
        widgetWindow.appendChild(widgetIframe);

View on GitHub (pinned to db67585ee2)

Solutions

Ensure GitBook('init', { siteURL: 'https://your-site.gitbook.io/...' }) runs before any other GitBook(...) call
Verify the standalone script is loaded and init is not wrapped in a condition that skips it
If init is async in your flow, await it or issue subsequent commands from its callback/promise

Example fix

// before
GitBook('getColorScheme'); // no init yet

// after
GitBook('init', { siteURL: 'https://docs.example.com/' });
GitBook('getColorScheme');

Defensive patterns

Strategy: validation

Validate before calling

let initialized = false;
if (!initialized) {
    GitBook('init', { siteURL: 'https://docs.example.com/' });
    initialized = true;
}
GitBook('getColorScheme');

Prevention

Make init the first GitBook call in your bootstrap script
Keep init at top-level of the embed snippet, not inside conditional branches
Check the @gitbook/embed docs when upgrading, as init options may change

When it happens

Trigger: Calling GitBook('getColorScheme') or any client-dependent command before GitBook('init', { siteURL: '...' }); loading the standalone script and immediately issuing commands; init failing silently (e.g. script not fully loaded) so _client is never set.

Common situations: Copy-pasting the embed snippet but removing or reordering the init call; race where commands run in a script placed before init; misspelling 'init' or the siteURL option; upgrading @gitbook/embed where the init API surface changed.

Related errors

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