{"record":{"id":"08f7a5a4a0d2a8d5","repo":"influxdata/influxdb","slug":"persisted-catalog-checkpoint-sequence-checkpoint-sequence-is","errorCode":null,"errorMessage":"persisted catalog checkpoint sequence {checkpoint_sequence} is ahead of live catalog sequence {live_sequence}","messagePattern":"persisted catalog checkpoint sequence (.+?) is ahead of live catalog sequence (.+?)","errorType":"error_code","errorClass":"CatalogError","httpStatus":null,"severity":"critical","filePath":"influxdb3_catalog/src/error.rs","lineNumber":67,"sourceCode":"\n    #[error(\"attempted to create a resource that already exists\")]\n    AlreadyExists,\n\n    #[error(\"the requested resource was not found: {0}\")]\n    NotFound(String),\n\n    #[error(\"attempted to modify resource that was already deleted: {0}\")]\n    AlreadyDeleted(String),\n\n    /// Request is idempotent: no catalog state would change.\n    #[error(\"no catalog changes to apply: {details}\")]\n    NoCatalogChange { details: String },\n\n    /// Request is invalid.\n    #[error(\"catalog internal error: {details}\")]\n    Internal { details: String },\n\n    #[error(\n        \"persisted catalog checkpoint sequence {checkpoint_sequence} is ahead of live catalog sequence {live_sequence}\"\n    )]\n    BackupCheckpointAhead {\n        checkpoint_sequence: u64,\n        live_sequence: u64,\n    },\n\n    #[error(\"invalid configuration provided: {message}\")]\n    InvalidConfiguration { message: Box<str> },\n\n    #[error(\"only tag and string columns are supported in the distinct cache\")]\n    InvalidDistinctCacheColumnType,\n\n    #[error(\"only uint64, int64, bool, tag, and string columns are supported in the last cache\")]\n    InvalidLastCacheKeyColumnType,\n\n    #[error(\"plugin trigger is already enabled\")]\n    TriggerAlreadyEnabled,","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/influxdata/influxdb/blob/06200ef96ba82c5f6727e5038a83af8e722c6875/influxdb3_catalog/src/error.rs#L49-L85","documentation":"CatalogError::BackupCheckpointAhead is thrown when a persisted catalog checkpoint from a backup/restore source has a sequence number greater than the live in-memory catalog sequence. This means restoring the backup would roll the catalog backward, so the library refuses. It guards against data loss and monotonic-sequence corruption.","triggerScenarios":"Restoring a catalog snapshot/checkpoint whose checkpoint_sequence exceeds the live catalog's sequence; pointing a node at a backup newer than its WAL/current catalog; replaying an old WAL after a newer checkpoint was restored.","commonSituations":"Operator restores a backup from the wrong (newer) environment; snapshot copied from a replicated node while the target kept advancing; clock/sequence drift after failover.","solutions":["Restore using the checkpoint that is not newer than the live catalog, or reset the live catalog sequence to accept the backup via the documented restore path","Verify you are restoring into the correct environment/node","Compare checkpoint_sequence vs live_sequence in the message before deciding","If intentional, wipe the live catalog store first so the backup becomes authoritative"],"exampleFix":"// before\n// restoring newer backup over running node with live seq 42, checkpoint seq 57\n// after\n// stop node, clear catalog dir, then restore\ninfluxdb3 serve --object-store file --data-dir /restored  # clean dir loaded from backup","handlingStrategy":"validation","validationCode":"// Rust: refuse restore when backup is ahead of live\nif backup.checkpoint_sequence > live.catalog_sequence() {\n    return Err(\"backup checkpoint is ahead of live catalog; restore into a clean store\".into());\n}","typeGuard":null,"tryCatchPattern":"match restore(backup).await {\n    Err(CatalogError::BackupCheckpointAhead { checkpoint_sequence, live_sequence }) => {\n        error!(cp = checkpoint_sequence, live = live_sequence,\n               \"restore aborted: backup newer than live; wipe live store first\");\n    }\n    other => other?,\n}","preventionTips":["Always restore into a clean/empty catalog store","Label backups with environment and sequence numbers","Stop the node before restore operations","Verify backup source/target pairs before copying"],"tags":["backup","restore","sequence","catalog"],"backgroundTag":"invalid-state-transition","analyzedSha":"06200ef96ba82c5f6727e5038a83af8e722c6875","analyzedAt":"2026-09-19T12:55:30.003Z","contentChangedAt":"2026-09-19T12:55:30.003Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}