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

Check the printed path: ensure every component exists, is a directory, and is writable by the process user (chmod/chown).

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

Couldn't create backup engine options for path `{}`: {}

Error message

Couldn't create backup engine options for path `{}`: {}

What it means

While creating the RocksDB backup engine, BackupEngineOptions::new(backup_dir/Description::name()) failed and is wrapped as DatabaseError::BackupEngineInitError. This is an OS-level rejection of the backup directory path — invalid path, missing permissions, or an unwritable filesystem.

Source

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

    #[cfg(feature = "backup")]
    fn backup_engine<P: AsRef<Path> + ?Sized>(
        backup_dir: &P,
    ) -> DatabaseResult<rocksdb::backup::BackupEngine> {
        use rocksdb::{
            Env,
            backup::{
                BackupEngine,
                BackupEngineOptions,
            },
        };

        let backup_dir = backup_dir.as_ref().join(Description::name());
        let backup_dir_path = backup_dir.as_path();

        let mut backup_engine_options = BackupEngineOptions::new(backup_dir_path)
            .map_err(|e| {
                DatabaseError::BackupEngineInitError(anyhow::anyhow!(
                    "Couldn't create backup engine options for path `{}`: {}",
                    backup_dir_path.display(),
                    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
            ))
        })?;

View on GitHub (pinned to b9d4d170da)

Solutions

Check the printed path: ensure every component exists, is a directory, and is writable by the process user (chmod/chown).
Use an absolute path for the backup directory to avoid cwd-dependent resolution.
Verify disk space and that the backup volume is mounted rw, not ro.
Read the trailing OS error in the message for the exact syscall failure.

Defensive patterns

Strategy: validation

Validate before calling

use std::path::Path;

fn backup_dir_usable(dir: &Path) -> anyhow::Result<()> {
    if dir.exists() && !dir.is_dir() {
        return Err(anyhow::anyhow!("backup path {} is not a directory", dir.display()));
    }
    std::fs::create_dir_all(dir)?;
    let probe = dir.join(".write_probe");
    std::fs::write(&probe, b"x")?;
    std::fs::remove_file(probe)?;
    Ok(())
}

// run before fuel_core::state::rocks_db::RocksDb::<D>::backup

Try / catch

match RocksDb::<Description>::backup(db_dir, backup_dir, db_config) {
    Err(e) if e.to_string().contains("backup engine options") => {
        // fix path/permissions for backup_dir, then retry
    }
    rest => rest,
}

Prevention

Use absolute backup paths in node configs and runbooks.
Provision the backup directory with correct ownership before enabling backups.
Verify the backup volume is mounted rw and has space.

When it happens

Trigger: Calling RocksDb::<Description>::backup(db_dir, backup_dir, db_config) with a backup directory that cannot be created or opened: permission denied, read-only filesystem, a malformed path, or a path component that is a regular file.

Common situations: Running the node or backup command as a user without write access to the backup location; read-only container mounts; relative backup paths resolved from an unexpected working directory.

Related errors

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