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

Free space on the backup volume (a backup is roughly the size of the database) and retry.

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

Couldn't create new backup for path `{}`: {}

Error message

Couldn't create new backup for path `{}`: {}

What it means

BackupEngine::create_new_backup_flush(&db, true) failed during DatabaseDescription::backup, wrapped as DatabaseError::BackupError. The node opens the database read-only and flushes it into a new backup; failure is an I/O-level error while writing the backup — disk full, write error on the volume, or the source db being in a bad or locked state.

Source

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

        let mut backup_engine = Self::backup_engine(backup_dir)?;

        let db_config = DatabaseConfig {
            cache_capacity: None,
            max_fds: -1,
            columns_policy: ColumnsPolicy::Lazy,
        };

        let db = Self::open_read_only(
            db_dir,
            enum_iterator::all::<Description::Column>().collect::<Vec<_>>(),
            false,
            db_config,
        )?;

        backup_engine
            .create_new_backup_flush(&db.db, true)
            .map_err(|e| {
                DatabaseError::BackupError(anyhow::anyhow!(
                    "Couldn't create new backup for path `{}`: {}",
                    backup_dir.as_ref().display(),
                    e
                ))
            })?;

        Ok(())
    }

    /// We delegate opening of restored db to consumer, so they can apply their own options
    #[cfg(feature = "backup")]
    pub fn restore<P: AsRef<Path> + ?Sized>(
        db_dir: &P,
        backup_dir: &P,
    ) -> DatabaseResult<()> {
        use rocksdb::backup::RestoreOptions;

        let mut backup_engine = Self::backup_engine(backup_dir)?;

View on GitHub (pinned to b9d4d170da)

Solutions

Free space on the backup volume (a backup is roughly the size of the database) and retry.
Make sure no other process holds RocksDB locks on the db directory and the node is not being migrated concurrently.
Check dmesg and filesystem health for IO errors; move the backup directory to a healthy volume.
If the source db is suspected corrupt, repair it or restore from an earlier backup before backing up again.

Defensive patterns

Strategy: try-catch

Validate before calling

fn enough_space_for_backup(path: &std::path::Path, db_size: u64) -> bool {
    // compare available space (statvfs) against the db size; backups are roughly db-sized
    nix::sys::statvfs::statvfs(path)
        .map(|s| (s.blocks_available() as u64) * s.fragment_size() >= db_size)
        .unwrap_or(false)
}

Try / catch

match RocksDb::<Description>::backup(db_dir, backup_dir, db_config) {
    Err(e) if e.to_string().contains("Couldn't create new backup") => {
        // free disk space, ensure the db is not locked or corrupt, then retry
    }
    rest => rest,
}

Prevention

Monitor free space on the backup volume and alert before it fills.
Size backup volumes for at least the current db size plus growth headroom.
Avoid running backup while migrating or compacting the db.

When it happens

Trigger: Running backup with insufficient disk space in the backup directory; IO errors on the backup volume; backing up database files that are corrupted or concurrently locked by another process.

Common situations: Scheduled backups on nodes whose state has grown to fill the disk; backups taken during heavy write load; filesystem or hardware problems on the backup mount.

Related errors

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