gitbutlerapp/gitbutler · error

Failed to rename {} to {} - application may fail to startup:

Error message

Failed to rename {} to {} - application may fail to startup: {err}

What it means

Thrown during the app's startup database quarantine (gitbutler-tauri) when opening the project db failed and moving the broken file aside also fails. The recovery flow renames the db to <db_name>.maybe-broken-NN so a fresh one can be created; if std::fs::rename itself errors, the quarantine cannot proceed and startup is at risk, as the message warns.

Source

Thrown at crates/gitbutler-tauri/src/projects.rs:143

                         this app was used to open the project. '{}' is incompatible",
                        db_path.display()
                    )
                })
                .context(but_error::Code::ProjectDatabaseIncompatible);
        }
        let db_filename = db_path.file_name().unwrap();
        let max_attempts = 255;
        for round in 1..max_attempts {
            let backup_path = data_dir.join(format!(
                "{db_name}.maybe-broken-{round:02}",
                db_name = Path::new(db_filename).display()
            ));
            if backup_path.is_file() {
                continue;
            }

            if let Err(err) = std::fs::rename(&db_path, &backup_path) {
                bail!(
                    "Failed to rename {} to {} - application may fail to startup: {err}",
                    db_path.display(),
                    backup_path.display()
                );
            }

            return Ok(Some(format!(
                "Could not open db file at '{}'.\nIt was moved to {} for recovery. \n\nError was: {err}",
                db_path.display(),
                backup_path.display()
            )));
        }
        bail!(
            "Database file at '{db_path} has {max_attempts} corrupted copies - giving up, application probably won't work",
            db_path = db_path.display()
        );
    }
    Ok(None)

View on GitHub (pinned to caf1f223d3)

Solutions

  1. Close every GitButler process, temporarily exclude the data dir from AV/backup scanning, and relaunch so the quarantine rename can succeed
  2. Free disk space and fix write permissions on the data directory
  3. Rename the broken db manually to a .maybe-broken name so the app creates a fresh one
  4. Ensure the data dir sits on a local, writable volume
Defensive patterns

Strategy: try-catch

Validate before calling

// pre-flight: can we write next to the db?
let probe = db_path.with_extension("rename-probe");
std::fs::write(&probe, b"")?;
std::fs::remove_file(&probe)?;

Try / catch

match open_db_with_recovery(&db_path) {
    Err(e) if e.to_string().contains("Failed to rename") => {
        // quarantine blocked: report which process may hold the file,
        // offer a manual move; never delete the db
    }
    r => r,
}

Prevention

When it happens

Trigger: The db open failed, and the quarantine rename of db_path to data_dir/<db_name>.maybe-broken-NN returns Err - typical on Windows when another process (antivirus, backup agent, second app instance) holds the file open, or when the volume is full or read-only.

Common situations: Antivirus or backup software locking the db during startup; two app instances launched simultaneously; data directory made read-only by permissions changes or corporate policy; the data dir on a network/removable mount that disappeared.

Related errors

AI-assisted analysis of gitbutlerapp/gitbutler@caf1f223d3 (2026-08-20). Data as JSON: /api/errors/2859bcd5bfa9619e. Report an issue: GitHub.