What causes "restore checkpoint not found at {checkpoint_path}" in influxdata/influxdb?

Verify the checkpoint_path exists in the configured object store (list the prefix via the store CLI/console).

influxdata/influxdb · error · FormatError

restore checkpoint not found at

Error message

restore checkpoint not found at {checkpoint_path}

What it means

The backup snapshot referenced by a RestoreCatalog record was not found at the recorded checkpoint path ({checkpoint_path}). The restore machinery resolved and parsed the path but the object simply does not exist, so there is no snapshot to load backup state from.

Solutions

Verify the checkpoint_path exists in the configured object store (list the prefix via the store CLI/console).
Point the instance at the correct bucket/prefix for the backup.
Re-run the restore from an available, intact snapshot if the referenced one is unrecoverable.
Disable/adjust lifecycle expiry rules that could delete catalog checkpoints.

Example fix

// before: aws s3 ls s3://wrong-bucket/catalog-checkpoints/...
// after: use the bucket the backup was taken from
// aws s3 ls s3://original-backup-bucket/influxdb3/catalog-checkpoints/...

Defensive patterns

Strategy: validation

Validate before calling

// Confirm the checkpoint exists before attempting restore
let exists = store.head_object(&checkpoint_path).await.is_ok();
if !exists {
    return Err(format!("checkpoint missing: {}", checkpoint_path));
}

Try / catch

match apply_restore(record).await {
    Err(e) if e.to_string().contains("checkpoint not found") => pick_alternative_snapshot()?,
    r => r,
}

Prevention

Exclude catalog checkpoint prefixes from object-store lifecycle/expiry rules
Verify bucket/prefix configuration matches the backup environment
List available checkpoints and choose an existing one before restoring

When it happens

Trigger: Applying a RestoreCatalog record whose checkpoint snapshot was deleted, expired by a lifecycle rule, or never fully uploaded; pointing at the wrong bucket/prefix so the recorded path does not resolve.

Common situations: Object-store lifecycle policies deleting old snapshots; someone cleaned the backup prefix; bucket misconfiguration; restoring into a different environment than the backup came from.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at influxdb3_catalog/src/format/mod.rs:237

        "RestoreCatalog record encountered without object-store access \
         (sync apply path): the catalog cannot reload backup state from \
         here — use the async apply path"
    )]
    RestoreRequiresStore,

    /// Loading the backup snapshot/log files referenced by a `RestoreCatalog`
    /// record failed.
    #[error("failed to load restore source: {0}")]
    RestoreLoadFailed(String),

    /// The checkpoint or log path in a `RestoreCatalog` record could not be
    /// parsed as an object-store path.
    #[error("invalid restore path: {0}")]
    InvalidRestorePath(String),

    /// The backup snapshot referenced by a `RestoreCatalog` record was not
    /// found at the recorded checkpoint path.
    #[error("restore checkpoint not found at {checkpoint_path}")]
    RestoreCheckpointMissing { checkpoint_path: String },

    /// A decoded record could not be serialized to a value for inspection.
    #[error("failed to serialize record id {record_id} to value: {reason}")]
    RecordToValue { record_id: u16, reason: String },
}

#[cfg(test)]
mod tests;

View on GitHub (pinned to 06200ef96b)