gitbutlerapp/gitbutler · error

Repository path is not valid UTF-8

Error message

Repository path is not valid UTF-8

What it means

Thrown by `setup_local_remote` on the gb-local fallback path: `repo.workdir()` exists, but converting the path to a string with `to_str()` fails because the path contains bytes that are not valid UTF-8. Rust `Path::to_str` returns None for such paths, and the remote URL must be a String, so setup aborts before writing the remote config.

Source

Thrown at crates/but/src/command/legacy/setup.rs:540

            .remote_default_name(gix::remote::Direction::Push)
            .is_none()
    {
        anyhow::bail!(
            "Neither found push remote found in workspace nor unambiguously in the Git repository configuration."
        )
    };

    Ok(true)
}

/// Creates a 'gb-local' remote pointing to this repository and creates tracking refs for the default branch.
fn setup_local_remote(repo: &gix::Repository, out: &mut OutputChannel) -> anyhow::Result<String> {
    let t = theme::get();
    let repo_url = repo
        .workdir()
        .ok_or_else(|| anyhow::anyhow!("Repository has no working directory"))?
        .to_str()
        .ok_or_else(|| anyhow::anyhow!("Repository path is not valid UTF-8"))?;

    if let Some(out) = out.for_human() {
        writeln!(
            out,
            "  {}",
            t.info
                .paint("No push remote found, creating gb-local remote...")
        )?;
    }

    edit_repo_config(repo, gix::config::Source::Local, |config| {
        let mut section = config.section_mut_or_create_new("remote", Some("gb-local".into()))?;
        section.push("url", repo_url)?;
        Ok(())
    })?;

    // Figure out what local branch is probably the default target
    let mut head_ref = repo.head()?;

View on GitHub (pinned to caf1f223d3)

Solutions

1. Move or rename the repository to a path that is valid UTF-8 (`mv` with a fresh typed name), then rerun setup
2. Add a push remote so the gb-local fallback (which needs the UTF-8 URL) is skipped entirely
3. Alternatively create a UTF-8 symlink to the repo directory and run setup through the symlink path

Example fix

# before: path has invalid bytes
cd $'~/work/proj\xff' && but setup

# after: rename to a UTF-8 path
mv $'~/work/proj\xff' ~/work/project
but setup ~/work/project

let Some(url) = repo.workdir().and_then(|p| p.to_str()) else {
    anyhow::bail!("repo path is not valid UTF-8; rename the directory or add a push remote");
};
// safe to build the gb-local URL from `url`

match setup_local_remote(&repo, &mut out) {
    Ok(remote) => { /* use remote */ }
    Err(err) if err.to_string().contains("not valid UTF-8") => {
        // move repo to a UTF-8 path or configure a push remote
    }
    Err(err) => return Err(err),
}

When it happens

Trigger: The repository lives under a directory whose name has non-UTF-8 bytes (e.g. legacy Latin-1 encoded names on Unix), and setup runs with no push remote configured so `gb-local` URL construction is attempted.

Common situations: Older Unix filesystems with non-UTF-8 locale encodings; archives or tools that materialized byte-escaped directory names; names containing unpaired surrogate-ish byte sequences from mis-decompressed data.

Related errors

• The path {} does not exist
• The path {} is not a directory
• Repository has no working directory
• The repository at {} is bare. GitButler requires a non-bare
• The repository at {} is a non-main worktree. GitButler requi

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