influxdata/influxdb · error · FormatError

RestoreCatalog record encountered without object-store…

Error message

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

What it means

A RestoreCatalog record was being applied through the synchronous apply path while the restore preload (backup state loaded from object storage) was empty. Restoring requires reading backup snapshot/log files from the object store, which the sync path cannot do (it runs while holding the catalog lock and has no store access). The caller must preload the backup state off-lock first and pass it in.

Solutions

1. Before the sync apply, call preload_restore_for_records (or preload_restore_for_file) to load the backup state.
2. Pass the resulting RestorePreload into the apply call.
3. Or switch to the async apply path, which can access the object store directly.

Example fix

// before
// catalog.apply_in_sync(records)?;
// after
// let preload = catalog.preload_restore_for_records(&records)?;
// catalog.apply_in_sync_with_preload(records, preload)?;

// Detect restore records in the batch before sync apply
if records.iter().any(|r| matches!(r, Record::RestoreCatalog(_))) {
    let preload = catalog.preload_restore_for_records(&records)?; // off-lock, uses store
    return catalog.apply_with_preload(records, preload);
}

match catalog.apply_in_sync(records) {
    Err(e) if e.to_string().contains("RestoreCatalog") => {
        let preload = catalog.preload_restore_for_records(&records)?;
        catalog.apply_with_preload(records, preload)
    }
    r => r,
}

When it happens

Trigger: Calling the sync apply API (e.g. catalog.apply with sync semantics) on a record batch that includes a RestoreCatalog record without first calling preload_restore_for_records / preload_restore_for_file and supplying the resulting RestorePreload.

Common situations: Writing custom replay/compaction code over catalog logs and forgetting the preload step when a restore record may appear; replaying a historical log segment containing a restore operation.

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
• persisted catalog checkpoint sequence
• restore checkpoint not found at
• {0}
• Adding a new database would exceed limit of

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

Appendix: source

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

        "record data exceeds file bounds: offset {offset}, length {length}, file size {file_size}"
    )]
    RecordExceedsFile {
        offset: u64,
        length: u32,
        file_size: u64,
    },

    /// File header is internally inconsistent (e.g. a reserved field is
    /// nonzero).
    #[error("invalid header: {reason}")]
    InvalidHeader { reason: &'static str },

    /// A `RestoreCatalog` record was encountered during sync apply with an
    /// empty preload. Callers on a persistence path must first load the
    /// backup state off-lock via `preload_restore_for_records` /
    /// `preload_restore_for_file` and pass the resulting `RestorePreload`
    /// into the apply call.
    #[error(
        "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.

View on GitHub (pinned to 06200ef96b)