GitoxideLabs/gitoxide · error

no illformed UTF-8

Error message

no illformed UTF-8

What it means

Same function as error 534: after extracting the file name, the helper converts the `OsStr` to a `BStr` with `gix_path::os_str_into_bstr(...).expect("no illformed UTF-8")`. The conversion only fails on non-Unicode-convertible OS strings, so the expect asserts the worktree directory name is valid. A worktree directory containing unencodable bytes on Unix (e.g. invalid UTF-8 in the name) triggers the panic.

Solutions

1. Rename the worktree directory (and update `.git/worktrees` metadata, e.g. via `git worktree` commands) to use valid UTF-8.
2. Avoid creating worktrees whose names come from untrusted byte sources; validate names are UTF-8 first.
3. Report to gitoxide if stricter non-panicking conversion is preferred.

Example fix

// before
let name = std::str::from_utf8(os_bytes).unwrap();
// after (caller-side validation)
let name = std::str::from_utf8(os_bytes)
    .expect("worktree name must be valid UTF-8"); // validated before creating the worktree

let name = git_dir.file_name().and_then(|n| n.to_str());
if name.is_none() { return Err(anyhow::anyhow!("worktree dir name is not UTF-8")); }

fn valid_utf8_name(p: &std::path::Path) -> bool { p.file_name().map_or(false, |n| n.to_str().is_some()) }

When it happens

Trigger: A linked worktree whose directory name under `.git/worktrees/` contains bytes that are not valid UTF-8 (possible on Linux filesystems), then accessing worktree APIs that call this helper.

Common situations: Worktree names created by scripts with raw bytes, locale-dependent names, or files created with non-UTF-8 encodings; mostly Linux/Unix.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• no illformed UTF-8
• Illformed UTF-8
• shell assignment names contain only ASCII bytes
• at least one directory level
• worktrees/ parent dir

AI-assisted analysis of GitoxideLabs/gitoxide@e73179060b (2026-09-08). Data as JSON: /api/errors/d4544f9650bcc14d. Report an issue: GitHub.

Appendix: source

Thrown at gix/src/worktree/mod.rs:110

    /// Return the ID of the repository worktree, if it is a linked worktree, or `None` if it's a linked worktree.
    pub fn id(&self) -> Option<&BStr> {
        id(self.parent.git_dir(), self.parent.common_dir.is_some())
    }

    /// Returns true if the `.git` file or directory exists within the worktree.
    ///
    /// This is an indicator for the worktree to be checked out particularly if the parent repository is a submodule.
    pub fn dot_git_exists(&self) -> bool {
        self.path.join(gix_discover::DOT_GIT_DIR).exists()
    }
}

pub(crate) fn id(git_dir: &std::path::Path, has_common_dir: bool) -> Option<&BStr> {
    if !has_common_dir {
        return None;
    }
    let candidate = gix_path::os_str_into_bstr(git_dir.file_name().expect("at least one directory level"))
        .expect("no illformed UTF-8");
    let maybe_worktrees = git_dir.parent()?;
    (maybe_worktrees.file_name()?.to_str()? == "worktrees").then_some(candidate)
}

///
pub mod proxy;

///
#[cfg(feature = "index")]
pub mod open_index {
    /// The error returned by [`Worktree::open_index()`][crate::Worktree::open_index()].
    #[derive(Debug, thiserror::Error)]
    #[expect(missing_docs)]
    pub enum Error {
        #[error(transparent)]
        ConfigIndexThreads(#[from] crate::config::key::GenericErrorWithValue),
        #[error(transparent)]
        ConfigSkipHash(#[from] crate::config::boolean::Error),

View on GitHub (pinned to e73179060b)