gleam-lang/gleam · error

Output should be UTF-8

Error message

Output should be UTF-8

What it means

A guard in the git-integration error mapping of the CLI. `git_stdout` converts raw `git` command stdout bytes into an EcoString and this message fires when `String::from_utf8` fails, i.e. `git` emitted output that is not valid UTF-8. The input at fault is the captured stdout of a spawned `git` process (e.g. a repository path, branch name, or tag containing non-UTF-8 bytes), typically due to unusual filenames or locale settings on the user's system.

Solutions

1. Rename the offending git repository, directory, or tag/branch to use only UTF-8/ASCII characters
2. Set a UTF-8 locale (LANG/LC_ALL=C.UTF-8) so git output is UTF-8 encoded
3. Check git config (core.quotepath=false) and avoid non-UTF-8 ref names in the dependency repo
4. Report to the Gleam repo — decoding should use from_utf8_lossy instead of expect

# Ensure UTF-8 environment before running git-dependent commands
export LANG=C.UTF-8
export LC_ALL=C.UTF-8

When it happens

Trigger: A `git` command run during dependency fetching (e.g. resolving a git dependency's refs/HEAD) whose stdout contains non-UTF-8 bytes, such as repo directory names, ref names, or commit messages in a non-UTF-8 locale.

Common situations: Git dependencies whose local path or tag names contain non-UTF-8 characters; machines with legacy locales (e.g. Latin-1 filesystem encoding); git configuration that prints localized output with non-UTF-8 characters.

Understand the failure class

Background: "git command failed": what it means when a tool shells out to git and git exits non-zero — this error's family across 21 libraries.

Related errors

• Non Utf-8 Path
• Non Utf-8 Path
• Non Utf8 Path
• Non Utf8 Path
• Non-UTF8 path in hardlink_dir

AI-assisted analysis of gleam-lang/gleam@15b07c7830 (2026-09-14). Data as JSON: /api/errors/6cea0d9cff4e502f. Report an issue: GitHub.

Appendix: source

Thrown at compiler-cli/src/dependencies.rs:1133

/// Map an IO error from spawning `git` onto the appropriate `Error`.
fn git_io_error(error: std::io::Error) -> Error {
    match error.kind() {
        ErrorKind::NotFound => Error::ShellProgramNotFound {
            program: "git".into(),
            os: fs::get_os(),
        },
        other => Error::ShellCommand {
            program: "git".into(),
            reason: ShellCommandFailureReason::IoError(other),
        },
    }
}

/// Parse the trimmed UTF-8 stdout of a `git` command.
fn git_stdout(output: std::process::Output) -> EcoString {
    String::from_utf8(output.stdout)
        .expect("Output should be UTF-8")
        .trim()
        .into()
}

fn git_repo_dir_name(repo: &str) -> String {
    let name = repo
        .trim_end_matches('/')
        .trim_end_matches(".git")
        .rsplit(['/', ':', '\\'])
        .next()
        .filter(|name| !name.is_empty())
        .unwrap_or("repo");
    let hash = xxhash_rust::xxh3::xxh3_64(repo.as_bytes());
    format!("{name}-{hash:016x}")
}

fn git_staging_path(project_paths: &ProjectPaths, repo: &str, package_name: &str) -> Utf8PathBuf {
    project_paths.build_git_repo(&format!(

View on GitHub (pinned to 15b07c7830)