TryGhost/Ghost · error · VersionMismatchError

API server is running a newer version of Ghost, please upgra

Error message

API server is running a newer version of Ghost, please upgrade.

What it means

VersionMismatchError, thrown by handleResponse when the JSON error body's errors[0].type === 'VersionMismatchError'. It means the Ghost server is running a newer API version than the admin client expects — typically the server was upgraded but the admin client build is stale, or vice-versa. The client cannot safely talk to this server version.

Source

Thrown at apps/admin-x-framework/src/utils/api/handle-response.ts:27

        throw new UnsupportedMediaTypeError(response, await response.text());
    } else if (response.status === 413) {
        throw new RequestEntityTooLargeError(response, await response.text());
    } else if (response.status === 401) {
        if (response.headers.get('content-type')?.includes('json')) {
            throw new UnauthorizedError(response, await response.json());
        }
        throw new UnauthorizedError(response, await response.text());
    } else if (!response.ok) {
        if (!response.headers.get('content-type')?.includes('json')) {
            throw new APIError(response, await response.text());
        }

        const data = await response.json() as ErrorResponse;

        if (response.status === 403 && data.errors?.[0]?.message === 'Authorization failed') {
            throw new UnauthorizedError(response, data);
        } else if (data.errors?.[0]?.type === 'VersionMismatchError') {
            throw new VersionMismatchError(response, data);
        } else if (data.errors?.[0]?.type === 'ValidationError') {
            throw new ValidationError(response, data);
        } else if (data.errors?.[0]?.type === 'NoPermissionError') {
            throw new ValidationError(response, data);
        } else if (data.errors?.[0]?.type === 'ThemeValidationError') {
            throw new ThemeValidationError(response, data);
        } else if (data.errors?.[0]?.type === 'HostLimitError') {
            throw new HostLimitError(response, data);
        } else if (data.errors?.[0]?.type === 'EmailError') {
            throw new EmailError(response, data);
        } else {
            throw new JSONError(response, data);
        }
    } else if (response.status === 204) {
        return;
    } else if (response.headers.get('content-type')?.includes('text/csv')) {
        return await response.text();
    } else {

View on GitHub (pinned to 47d8b0e2ad)

Solutions

1. Hard-refresh / clear cache to load the admin bundle matching the running Ghost version.
2. Confirm the admin assets shipped with this Ghost version (apps/*/dist copied into built/admin) are the ones being served.
3. Re-run the upgrade or rebuild admin if the mismatch persists after a cache clear.

import {VersionMismatchError} from '@tryghost/admin-x-framework/utils/errors';
function isVersionMismatch(e: unknown): e is VersionMismatchError {
    return e instanceof VersionMismatchError;
}

import {VersionMismatchError} from '@tryghost/admin-x-framework/utils/errors';
try {
    await api.settings.browse();
} catch (e) {
    if (e instanceof VersionMismatchError) {
        promptHardRefresh('Ghost was updated. Reload to get the latest admin.');
    } else throw e;
}

When it happens

Trigger: A Ghost upgrade has completed on the server but the user's browser is running a cached/older copy of the admin bundle; an admin-x app was built against a different Ghost major version than the running server.

Common situations: Post-upgrade cache staleness (old admin JS still served/cached); partial upgrade where one half of admin and server diverged; rollback then forward-upgrade mismatch.

Related errors

• Latest Stripe checkout session does not include a success UR

AI-assisted analysis of TryGhost/Ghost@47d8b0e2ad (2026-08-13). Data as JSON: /api/errors/149a5962a055c037. Report an issue: GitHub.