{"record":{"id":"aea20cae77ab3ae1","repo":"FuelLabs/fuel-core","slug":"couldn-t-create-backup-engine-options-for-path","errorCode":null,"errorMessage":"Couldn't create backup engine options for path `{}`: {}","messagePattern":"Couldn't create backup engine options for path `(.+?)`: (.+?)","errorType":"exception","errorClass":"DatabaseError::BackupEngineInitError","httpStatus":null,"severity":"error","filePath":"crates/fuel-core/src/state/rocks_db.rs","lineNumber":782,"sourceCode":"\n    #[cfg(feature = \"backup\")]\n    fn backup_engine<P: AsRef<Path> + ?Sized>(\n        backup_dir: &P,\n    ) -> DatabaseResult<rocksdb::backup::BackupEngine> {\n        use rocksdb::{\n            Env,\n            backup::{\n                BackupEngine,\n                BackupEngineOptions,\n            },\n        };\n\n        let backup_dir = backup_dir.as_ref().join(Description::name());\n        let backup_dir_path = backup_dir.as_path();\n\n        let mut backup_engine_options = BackupEngineOptions::new(backup_dir_path)\n            .map_err(|e| {\n                DatabaseError::BackupEngineInitError(anyhow::anyhow!(\n                    \"Couldn't create backup engine options for path `{}`: {}\",\n                    backup_dir_path.display(),\n                    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","sourceCodeStart":764,"sourceCodeEnd":800,"githubUrl":"https://github.com/FuelLabs/fuel-core/blob/b9d4d170da3a31c9ace5f963d633b326348e0d42/crates/fuel-core/src/state/rocks_db.rs#L764-L800","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"use std::path::Path;\n\nfn backup_dir_usable(dir: &Path) -> anyhow::Result<()> {\n    if dir.exists() && !dir.is_dir() {\n        return Err(anyhow::anyhow!(\"backup path {} is not a directory\", dir.display()));\n    }\n    std::fs::create_dir_all(dir)?;\n    let probe = dir.join(\".write_probe\");\n    std::fs::write(&probe, b\"x\")?;\n    std::fs::remove_file(probe)?;\n    Ok(())\n}\n\n// run before fuel_core::state::rocks_db::RocksDb::<D>::backup","typeGuard":null,"tryCatchPattern":"match RocksDb::<Description>::backup(db_dir, backup_dir, db_config) {\n    Err(e) if e.to_string().contains(\"backup engine options\") => {\n        // fix path/permissions for backup_dir, then retry\n    }\n    rest => rest,\n}","preventionTips":["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."],"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"}