{"record":{"id":"149a5962a055c037","repo":"TryGhost/Ghost","slug":"api-server-is-running-a-newer-version-of-ghost-pl","errorCode":null,"errorMessage":"API server is running a newer version of Ghost, please upgrade.","messagePattern":"API server is running a newer version of Ghost, please upgrade\\.","errorType":"http","errorClass":"VersionMismatchError","httpStatus":null,"severity":"error","filePath":"apps/admin-x-framework/src/utils/api/handle-response.ts","lineNumber":27,"sourceCode":"        throw new UnsupportedMediaTypeError(response, await response.text());\n    } else if (response.status === 413) {\n        throw new RequestEntityTooLargeError(response, await response.text());\n    } else if (response.status === 401) {\n        if (response.headers.get('content-type')?.includes('json')) {\n            throw new UnauthorizedError(response, await response.json());\n        }\n        throw new UnauthorizedError(response, await response.text());\n    } else if (!response.ok) {\n        if (!response.headers.get('content-type')?.includes('json')) {\n            throw new APIError(response, await response.text());\n        }\n\n        const data = await response.json() as ErrorResponse;\n\n        if (response.status === 403 && data.errors?.[0]?.message === 'Authorization failed') {\n            throw new UnauthorizedError(response, data);\n        } else if (data.errors?.[0]?.type === 'VersionMismatchError') {\n            throw new VersionMismatchError(response, data);\n        } else if (data.errors?.[0]?.type === 'ValidationError') {\n            throw new ValidationError(response, data);\n        } else if (data.errors?.[0]?.type === 'NoPermissionError') {\n            throw new ValidationError(response, data);\n        } else if (data.errors?.[0]?.type === 'ThemeValidationError') {\n            throw new ThemeValidationError(response, data);\n        } else if (data.errors?.[0]?.type === 'HostLimitError') {\n            throw new HostLimitError(response, data);\n        } else if (data.errors?.[0]?.type === 'EmailError') {\n            throw new EmailError(response, data);\n        } else {\n            throw new JSONError(response, data);\n        }\n    } else if (response.status === 204) {\n        return;\n    } else if (response.headers.get('content-type')?.includes('text/csv')) {\n        return await response.text();\n    } else {","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/TryGhost/Ghost/blob/47d8b0e2ad2fd4757d3bc45f46c3ac165ff8a1fe/apps/admin-x-framework/src/utils/api/handle-response.ts#L9-L45","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Hard-refresh / clear cache to load the admin bundle matching the running Ghost version.","Confirm the admin assets shipped with this Ghost version (apps/*/dist copied into built/admin) are the ones being served.","Re-run the upgrade or rebuild admin if the mismatch persists after a cache clear."],"exampleFix":null,"handlingStrategy":"type-guard","validationCode":null,"typeGuard":"import {VersionMismatchError} from '@tryghost/admin-x-framework/utils/errors';\nfunction isVersionMismatch(e: unknown): e is VersionMismatchError {\n    return e instanceof VersionMismatchError;\n}","tryCatchPattern":"import {VersionMismatchError} from '@tryghost/admin-x-framework/utils/errors';\ntry {\n    await api.settings.browse();\n} catch (e) {\n    if (e instanceof VersionMismatchError) {\n        promptHardRefresh('Ghost was updated. Reload to get the latest admin.');\n    } else throw e;\n}","preventionTips":["After a Ghost upgrade, hard-refresh / clear cache so the admin bundle matches the server version.","Ensure the served admin assets are the ones built with this Ghost version (asset-delivery copied the right dist).","Watch for this error after rollbacks/forward-upgrades — a mismatched client/server pair is the typical cause."],"tags":["version","upgrade","compatibility","api-version","cache"],"backgroundTag":null,"analyzedSha":"47d8b0e2ad2fd4757d3bc45f46c3ac165ff8a1fe","analyzedAt":"2026-08-13T01:25:26.651Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}