gleam-lang/gleam · error

Non Utf8 Path

Error message

Non Utf8 Path

What it means

This panic comes from an `.expect("Non Utf8 Path")` after canonicalising a file path and converting the std PathBuf back to a Utf8PathBuf. The gleam CLI assumes all paths it handles are valid UTF-8; if the canonicalised path contains bytes that are not valid UTF-8, `Utf8PathBuf::from_path_buf` returns Err and the expect panics. It is an internal invariant check, not a recoverable error.

Solutions

1. Rename the offending file or directory so its path is valid UTF-8 (e.g. `convmv --notest -f latin1 -t utf8 <path>`).
2. Check where the symlink resolves (`readlink -f <path>`) and ensure the target path is UTF-8.
3. Run the compiler with a UTF-8 locale (e.g. LANG=C.UTF-8) so tool-created names are UTF-8.
4. Patch the call site to use `to_string_lossy` or return an Error::FileIo instead of expecting, if you maintain a fork.

Example fix

// before
.map(|pb| Utf8PathBuf::from_path_buf(pb).expect("Non Utf8 Path"))
// after
.map(|pb| Utf8PathBuf::from_path_buf(pb).map_err(|_| Error::FileIo {
    action: FileIoAction::Canonicalise,
    kind: FileKind::File,
    path: Utf8PathBuf::from(path),
    err: Some("path is not valid UTF-8".into()),
}))

fn ensure_utf8_path(path: &std::path::Path) -> Result<Utf8PathBuf, String> {
    path.to_str()
        .map(|s| Utf8PathBuf::from(s.to_owned()))
        .ok_or_else(|| format!("path {:?} is not valid UTF-8", path))
}

fn is_utf8_path(p: &std::path::Path) -> bool { p.to_str().is_some() }

When it happens

Trigger: Calling the fs helper (canonicalise path around compiler-cli/src/fs.rs:881) with a path that, once canonicalised (symlinks resolved), resolves to a location whose name contains non-UTF-8 bytes, e.g. a symlink pointing into a directory with non-UTF-8 characters, on a filesystem using arbitrary byte sequences in names.

Common situations: Developers on Linux with filenames created in non-UTF-8 locales, or projects symlinked to directories with unusual byte-encoded names; macOS/Windows users rarely hit it since those filesystems enforce UTF-8-ish encodings.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Non-UTF8 path in hardlink_dir
• is_gleam_path(): strip_prefix
• Non Utf-8 Path
• Non Utf-8 Path
• Source path should be under base

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

Appendix: source

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

        Ok(_) => Ok(()),
        Err(err) => match err {
            Error::ShellProgramNotFound { .. } => Ok(()),
            _ => Err(Error::GitInitialization {
                error: err.to_string(),
            }),
        },
    }
}

pub fn canonicalise(path: &Utf8Path) -> Result<Utf8PathBuf, Error> {
    std::fs::canonicalize(path)
        .map_err(|err| Error::FileIo {
            action: FileIoAction::Canonicalise,
            kind: FileKind::File,
            path: Utf8PathBuf::from(path),
            err: Some(err.to_string()),
        })
        .map(|pb| Utf8PathBuf::from_path_buf(pb).expect("Non Utf8 Path"))
}

#[derive(Debug, Clone, Copy)]
pub struct ConsoleWarningEmitter;

impl WarningEmitterIO for ConsoleWarningEmitter {
    fn emit_warning(&self, warning: Warning) {
        let buffer_writer = crate::cli::stderr_buffer_writer();
        let mut buffer = buffer_writer.buffer();
        warning.pretty(&mut buffer);
        buffer_writer
            .print(&buffer)
            .expect("Writing warning to stderr");
    }
}

/// Returns root of Git repository in base path if it is initialised.
pub fn get_git_repository_root(mut path: Utf8PathBuf) -> Option<Utf8PathBuf> {

View on GitHub (pinned to 15b07c7830)