gleam-lang/gleam · critical

Non Utf-8 Path

Error message

Non Utf-8 Path

What it means

When enumerating Gleam source files, compiler-cli walks the directory tree with `ignore::WalkBuilder` (`follow_links(true)`, `standard_filters(false)`, build dir pruned) and converts every visited file to a `camino::Utf8PathBuf` via `Utf8PathBuf::from_path_buf(path).expect("Non Utf-8 Path")` (compiler-cli/src/fs.rs:475). On Unix a filename is raw bytes; any file whose name is not valid UTF-8 makes `from_path_buf` return None and the walk panics, aborting the build.

Source

Thrown at compiler-cli/src/fs.rs:475

/// Walks through all Gleam module files in the directory, even if ignored,
/// except for those in the `build/` directory. Excludes any Gleam files within
/// invalid module paths, for example if they or a folder they're in contain a
/// dot or a hyphen within their names.
pub fn gleam_files(dir: &Utf8Path) -> impl Iterator<Item = Utf8PathBuf> + '_ {
    ignore::WalkBuilder::new(dir)
        .follow_links(true)
        .standard_filters(false)
        .filter_entry(|entry| !is_gleam_build_dir(entry))
        .build()
        .filter_map(Result::ok)
        .filter(|entry| {
            entry
                .file_type()
                .map(|type_| type_.is_file())
                .unwrap_or(false)
        })
        .map(ignore::DirEntry::into_path)
        .map(|path| Utf8PathBuf::from_path_buf(path).expect("Non Utf-8 Path"))
        .filter(move |d| is_gleam_path(d, dir))
}

/// Walks through all native files in the directory, such as `.mjs` and `.erl`,
/// even if ignored.
pub fn native_files(dir: &Utf8Path) -> impl Iterator<Item = Utf8PathBuf> + '_ {
    ignore::WalkBuilder::new(dir)
        .follow_links(true)
        .standard_filters(false)
        .filter_entry(|entry| !is_gleam_build_dir(entry))
        .build()
        .filter_map(Result::ok)
        .filter(|entry| {
            entry
                .file_type()
                .map(|type_| type_.is_file())
                .unwrap_or(false)
        })

View on GitHub (pinned to 7e623aa83d)

Solutions

1. Locate offending names with a byte-walking scan (see the validation snippet in the defense section)
2. Rename the file to an ASCII/UTF-8 name using a printf-built path (e.g. `mv "$(printf 'src/test\xf1data')" src/test_f1data`) or delete it if it is junk
3. Re-run `gleam build` — the walk reruns each build, so the fix applies immediately
4. Re-extract the originating archive with the correct filename encoding (e.g. `unzip -O` variants or `convmv`) so the bad names do not come back

Example fix

# find files whose names are not valid UTF-8
python3 - <<'PY'
import os
for root, dirs, files in os.walk(b"."):
    if b"/build" in root:
        continue
    for n in dirs + files:
        try:
            n.decode("utf-8")
        except UnicodeDecodeError:
            print(os.path.join(root, n))
PY

# rename the offender, then rebuild
mv "$(printf 'src/test\xf1data')" src/test_f1data && gleam build

# pre-build check: list any filename that is not valid UTF-8
python3 - <<'PY'
import os, sys
bad = []
for root, dirs, files in os.walk(b"."):
    if b"/build" in root or b"/.git" in root:
        continue
    for n in dirs + files:
        try:
            n.decode("utf-8")
        except UnicodeDecodeError:
            bad.append(os.path.join(root, n))
print("\n".join(map(repr, bad)) or "all filenames UTF-8 safe")
sys.exit(1 if bad else 0)
PY
gleam build

When it happens

Trigger: Any regular file with invalid-UTF-8 bytes in its name inside the walked source tree (src/, test/, or the directory given to the walker): files extracted from archives created with latin-1/Shift-JIS/HFS+ names, mangled fixtures or blobs, or names written by misbehaving tooling. Because `standard_filters(false)` disables ignore rules, even .gitignored files are visited and can trigger the panic.

Common situations: A stray fixture like `test\xf1data` in src/ or test/; a teammate on another OS/encoding committing oddly named files (git stores filename bytes verbatim); vendor directories unpacked from third-party archives; junk files left by crashed editors or downloaders.

Related errors

• Non-UTF8 path in hardlink_dir
• BEAM compiler instance exited: {status}
• stdin read_line
• could not lock beam_compiler
• `panic` expression evaluated.

AI-assisted analysis of gleam-lang/gleam@7e623aa83d (2026-08-17). Data as JSON: /api/errors/7e28c18da09a6548. Report an issue: GitHub.