{"record":{"id":"afb4950568cd8f25","repo":"FuelLabs/fuel-core","slug":"couldn-t-open-backup-engine-for-path","errorCode":null,"errorMessage":"Couldn't open backup engine for path `{}`: {}","messagePattern":"Couldn't open backup engine for path `(.+?)`: (.+?)","errorType":"exception","errorClass":"DatabaseError::BackupEngineInitError","httpStatus":null,"severity":"error","filePath":"crates/fuel-core/src/state/rocks_db.rs","lineNumber":803,"sourceCode":"                    e\n                ))\n            })?;\n\n        let cpu_number =\n            i32::try_from(num_cpus::get()).expect(\"The number of CPU can't exceed `i32`\");\n\n        backup_engine_options.set_max_background_operations(cmp::max(1, cpu_number / 4));\n\n        let env = Env::new().map_err(|e| {\n            DatabaseError::BackupEngineInitError(anyhow::anyhow!(\n                \"Couldn't create environment for backup: {}\",\n                e\n            ))\n        })?;\n\n        let backup_engine =\n            BackupEngine::open(&backup_engine_options, &env).map_err(|e| {\n                DatabaseError::BackupEngineInitError(anyhow::anyhow!(\n                    \"Couldn't open backup engine for path `{}`: {}\",\n                    backup_dir.display(),\n                    e\n                ))\n            })?;\n\n        Ok(backup_engine)\n    }\n\n    #[cfg(feature = \"backup\")]\n    pub fn backup<P: AsRef<Path> + ?Sized>(\n        db_dir: &P,\n        backup_dir: &P,\n    ) -> DatabaseResult<()> {\n        let mut backup_engine = Self::backup_engine(backup_dir)?;\n\n        let db_config = DatabaseConfig {\n            cache_capacity: None,","sourceCodeStart":785,"sourceCodeEnd":821,"githubUrl":"https://github.com/FuelLabs/fuel-core/blob/b9d4d170da3a31c9ace5f963d633b326348e0d42/crates/fuel-core/src/state/rocks_db.rs#L785-L821","documentation":"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.","triggerScenarios":"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.","commonSituations":"Interrupted earlier backups leaving partial metadata; permissions changed between runs; disk exhaustion on the backup volume.","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."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"fn backup_engine_can_open(dir: &std::path::Path) -> anyhow::Result<()> {\n    std::fs::create_dir_all(dir)?;\n    let meta = std::fs::metadata(dir)?;\n    if !meta.is_dir() {\n        return Err(anyhow::anyhow!(\"{} is not a directory\", dir.display()));\n    }\n    Ok(())\n}\n\n// run before backup; if a previous run crashed, move the old dir aside first","typeGuard":null,"tryCatchPattern":"match RocksDb::<Description>::backup(db_dir, backup_dir, db_config) {\n    Err(e) if e.to_string().contains(\"Couldn't open backup engine\") => {\n        // check dir writability/space; archive or delete corrupt old backups; retry\n    }\n    rest => rest,\n}","preventionTips":["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."],"tags":["rocksdb","backup","filesystem","fuel-core","rust"],"backgroundTag":null,"analyzedSha":"b9d4d170da3a31c9ace5f963d633b326348e0d42","analyzedAt":"2026-08-16T08:56:42.692Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}