{"record":{"id":"2d322282e0cede17","repo":"influxdata/influxdb","slug":"restore-checkpoint-not-found-at-checkpoint-path","errorCode":null,"errorMessage":"restore checkpoint not found at {checkpoint_path}","messagePattern":"restore checkpoint not found at (.+?)","errorType":"error_code","errorClass":"FormatError","httpStatus":null,"severity":"error","filePath":"influxdb3_catalog/src/format/mod.rs","lineNumber":237,"sourceCode":"        \"RestoreCatalog record encountered without object-store access \\\n         (sync apply path): the catalog cannot reload backup state from \\\n         here — use the async apply path\"\n    )]\n    RestoreRequiresStore,\n\n    /// Loading the backup snapshot/log files referenced by a `RestoreCatalog`\n    /// record failed.\n    #[error(\"failed to load restore source: {0}\")]\n    RestoreLoadFailed(String),\n\n    /// The checkpoint or log path in a `RestoreCatalog` record could not be\n    /// parsed as an object-store path.\n    #[error(\"invalid restore path: {0}\")]\n    InvalidRestorePath(String),\n\n    /// The backup snapshot referenced by a `RestoreCatalog` record was not\n    /// found at the recorded checkpoint path.\n    #[error(\"restore checkpoint not found at {checkpoint_path}\")]\n    RestoreCheckpointMissing { checkpoint_path: String },\n\n    /// A decoded record could not be serialized to a value for inspection.\n    #[error(\"failed to serialize record id {record_id} to value: {reason}\")]\n    RecordToValue { record_id: u16, reason: String },\n}\n\n#[cfg(test)]\nmod tests;\n","sourceCodeStart":219,"sourceCodeEnd":247,"githubUrl":"https://github.com/influxdata/influxdb/blob/06200ef96ba82c5f6727e5038a83af8e722c6875/influxdb3_catalog/src/format/mod.rs#L219-L247","documentation":"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.","triggerScenarios":"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.","commonSituations":"Object-store lifecycle policies deleting old snapshots; someone cleaned the backup prefix; bucket misconfiguration; restoring into a different environment than the backup came 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."],"exampleFix":"// before: aws s3 ls s3://wrong-bucket/catalog-checkpoints/...\n// after: use the bucket the backup was taken from\n// aws s3 ls s3://original-backup-bucket/influxdb3/catalog-checkpoints/...","handlingStrategy":"validation","validationCode":"// Confirm the checkpoint exists before attempting restore\nlet exists = store.head_object(&checkpoint_path).await.is_ok();\nif !exists {\n    return Err(format!(\"checkpoint missing: {}\", checkpoint_path));\n}","typeGuard":null,"tryCatchPattern":"match apply_restore(record).await {\n    Err(e) if e.to_string().contains(\"checkpoint not found\") => pick_alternative_snapshot()?,\n    r => r,\n}","preventionTips":["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"],"tags":["restore","not-found","object-store","catalog"],"backgroundTag":"resource-not-found","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"}