influxdata/influxdb · critical · CatalogError

persisted catalog checkpoint sequence

Error message

persisted catalog checkpoint sequence {checkpoint_sequence} is ahead of live catalog sequence {live_sequence}

What it means

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.

Solutions

1. 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
2. Verify you are restoring into the correct environment/node
3. Compare checkpoint_sequence vs live_sequence in the message before deciding
4. If intentional, wipe the live catalog store first so the backup becomes authoritative

Example fix

// before
// restoring newer backup over running node with live seq 42, checkpoint seq 57
// after
// stop node, clear catalog dir, then restore
influxdb3 serve --object-store file --data-dir /restored  # clean dir loaded from backup

// Rust: refuse restore when backup is ahead of live
if backup.checkpoint_sequence > live.catalog_sequence() {
    return Err("backup checkpoint is ahead of live catalog; restore into a clean store".into());
}

match restore(backup).await {
    Err(CatalogError::BackupCheckpointAhead { checkpoint_sequence, live_sequence }) => {
        error!(cp = checkpoint_sequence, live = live_sequence,
               "restore aborted: backup newer than live; wipe live store first");
    }
    other => other?,
}

When it happens

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

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

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• failed to load restore source
• restore checkpoint not found at
• RestoreCatalog record encountered without object-store…
• {0}
• Adding a new database would exceed limit of

AI-assisted analysis of influxdata/influxdb@06200ef96b (2026-09-19). Data as JSON: /api/errors/08f7a5a4a0d2a8d5. Report an issue: GitHub.

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:67

    #[error("attempted to create a resource that already exists")]
    AlreadyExists,

    #[error("the requested resource was not found: {0}")]
    NotFound(String),

    #[error("attempted to modify resource that was already deleted: {0}")]
    AlreadyDeleted(String),

    /// Request is idempotent: no catalog state would change.
    #[error("no catalog changes to apply: {details}")]
    NoCatalogChange { details: String },

    /// Request is invalid.
    #[error("catalog internal error: {details}")]
    Internal { details: String },

    #[error(
        "persisted catalog checkpoint sequence {checkpoint_sequence} is ahead of live catalog sequence {live_sequence}"
    )]
    BackupCheckpointAhead {
        checkpoint_sequence: u64,
        live_sequence: u64,
    },

    #[error("invalid configuration provided: {message}")]
    InvalidConfiguration { message: Box<str> },

    #[error("only tag and string columns are supported in the distinct cache")]
    InvalidDistinctCacheColumnType,

    #[error("only uint64, int64, bool, tag, and string columns are supported in the last cache")]
    InvalidLastCacheKeyColumnType,

    #[error("plugin trigger is already enabled")]
    TriggerAlreadyEnabled,

View on GitHub (pinned to 06200ef96b)