What causes "Couldn't open backup engine for path `{}`: {}" in FuelLabs/fuel-core?

Inspect the printed path: confirm it is a directory, writable by the service user, with free space.

FuelLabs/fuel-core · error · DatabaseError::BackupEngineInitError

Couldn't open backup engine for path `{}`: {}

Error message

Couldn't open backup engine for path `{}`: {}

What it means

BackupEngine::open(&options, &env) failed for the given backup directory, wrapped as DatabaseError::BackupEngineInitError. Opening a backup engine creates and reads metadata inside the backup directory; failure means the directory is unusable (not writable, not a directory, disk full) or contains corrupt metadata from an earlier interrupted backup.

Source

Thrown at crates/fuel-core/src/state/rocks_db.rs:803

                    e
                ))
            })?;

        let cpu_number =
            i32::try_from(num_cpus::get()).expect("The number of CPU can't exceed `i32`");

        backup_engine_options.set_max_background_operations(cmp::max(1, cpu_number / 4));

        let env = Env::new().map_err(|e| {
            DatabaseError::BackupEngineInitError(anyhow::anyhow!(
                "Couldn't create environment for backup: {}",
                e
            ))
        })?;

        let backup_engine =
            BackupEngine::open(&backup_engine_options, &env).map_err(|e| {
                DatabaseError::BackupEngineInitError(anyhow::anyhow!(
                    "Couldn't open backup engine for path `{}`: {}",
                    backup_dir.display(),
                    e
                ))
            })?;

        Ok(backup_engine)
    }

    #[cfg(feature = "backup")]
    pub fn backup<P: AsRef<Path> + ?Sized>(
        db_dir: &P,
        backup_dir: &P,
    ) -> DatabaseResult<()> {
        let mut backup_engine = Self::backup_engine(backup_dir)?;

        let db_config = DatabaseConfig {
            cache_capacity: None,

View on GitHub (pinned to b9d4d170da)

Solutions

Inspect the printed path: confirm it is a directory, writable by the service user, with free space.
If a previous backup was interrupted or is corrupt, move the old backup directory aside (or delete it) so the engine can reinitialize.
Fix ownership and permissions, then retry the backup.

Defensive patterns

Strategy: validation

Validate before calling

fn backup_engine_can_open(dir: &std::path::Path) -> anyhow::Result<()> {
    std::fs::create_dir_all(dir)?;
    let meta = std::fs::metadata(dir)?;
    if !meta.is_dir() {
        return Err(anyhow::anyhow!("{} is not a directory", dir.display()));
    }
    Ok(())
}

// run before backup; if a previous run crashed, move the old dir aside first

Try / catch

match RocksDb::<Description>::backup(db_dir, backup_dir, db_config) {
    Err(e) if e.to_string().contains("Couldn't open backup engine") => {
        // check dir writability/space; archive or delete corrupt old backups; retry
    }
    rest => rest,
}

Prevention

Clean up partially written backups after interrupted runs.
Keep the backup directory on a dedicated, monitored volume.
Run the node under an account with write access to the backup path.

When it happens

Trigger: Calling backup with a backup directory that is not writable, is a file rather than a directory, is on a full volume, or already holds a corrupt or half-written backup from a crashed run.

Common situations: Interrupted earlier backups leaving partial metadata; permissions changed between runs; disk exhaustion on the backup volume.

Related errors

AI-assisted analysis of FuelLabs/fuel-core@b9d4d170da (2026-08-16). Data as JSON: /api/errors/afb4950568cd8f25. Report an issue: GitHub.