{"record":{"id":"7e28c18da09a6548","repo":"gleam-lang/gleam","slug":"non-utf-8-path","errorCode":null,"errorMessage":"Non Utf-8 Path","messagePattern":"Non Utf-8 Path","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"compiler-cli/src/fs.rs","lineNumber":476,"sourceCode":"/// Walks through all Gleam module files in the directory, even if ignored,\n/// except for those in the `build/` directory. Excludes any Gleam files within\n/// invalid module paths, for example if they or a folder they're in contain a\n/// dot or a hyphen within their names.\npub fn gleam_files(dir: &Utf8Path) -> impl Iterator<Item = Utf8PathBuf> + '_ {\n    ignore::WalkBuilder::new(dir)\n        .follow_links(true)\n        .standard_filters(false)\n        .filter_entry(|entry| !is_gleam_build_dir(entry))\n        .build()\n        .filter_map(Result::ok)\n        .filter(|entry| {\n            entry\n                .file_type()\n                .map(|type_| type_.is_file())\n                .unwrap_or(false)\n        })\n        .map(ignore::DirEntry::into_path)\n        .map(|path| Utf8PathBuf::from_path_buf(path).expect(\"Non Utf-8 Path\"))\n        .filter(move |d| is_gleam_path(d, dir))\n}\n\n/// Walks through all native files in the directory, such as `.mjs` and `.erl`,\n/// even if ignored.\npub fn native_files(dir: &Utf8Path) -> impl Iterator<Item = Utf8PathBuf> + '_ {\n    ignore::WalkBuilder::new(dir)\n        .follow_links(true)\n        .standard_filters(false)\n        .filter_entry(|entry| !is_gleam_build_dir(entry))\n        .build()\n        .filter_map(Result::ok)\n        .filter(|entry| {\n            entry\n                .file_type()\n                .map(|type_| type_.is_file())\n                .unwrap_or(false)\n        })","sourceCodeStart":458,"sourceCodeEnd":494,"githubUrl":"https://github.com/gleam-lang/gleam/blob/15b07c783065c92bb016b1b74ed0995a5259850f/compiler-cli/src/fs.rs#L458-L494","documentation":"A panic from `Utf8PathBuf::from_path_buf(path).expect(\"Non Utf-8 Path\")` in `gleam_files`: the directory walk encountered a file whose name is not valid UTF-8, and the crate (like most of the Rust ecosystem) requires UTF-8 paths. Gleam module names are lowercase identifiers, so a non-UTF-8 filename can never be a valid module anyway.","triggerScenarios":"Running any gleam command that scans the project's source directories (`gleam build`, `gleam deps download`, etc.) when the `src/` or `test/` tree contains a file or directory with non-UTF-8 bytes in its name — typically a file created with a legacy locale encoding.","commonSituations":"Files created on Linux with a non-UTF-8 locale (e.g. ISO-8859-1 filenames), files extracted from an archive with mis-encoded names, editor/OS artifacts with exotic names, files copied from other filesystems (NFS/FAT) with byte-level names.","solutions":["Locate the offending file and rename it to a UTF-8 (ideally plain ASCII lowercase) name: `find src -print0 | grep -zP '[^\\x00-\\x7F]'` then `mv` it.","Use `convmv -f latin1 -t utf-8 -r --notest src/` to batch-convert mis-encoded filenames.","Move the non-UTF-8 file (e.g. data files) out of `src/`/`test/` — only Gleam modules belong there.","On Linux, ensure the filesystem/locale is UTF-8 (`LANG=C.UTF-8`) so future files are created with valid names."],"exampleFix":"// shell: find and fix the non-UTF-8 filename before running gleam\nfind src -print0 | grep -zP '[^\\x00-\\x7F]'\nconvmv -f latin1 -t utf-8 -r --notest src/","handlingStrategy":"validation","validationCode":"// scan for non-UTF-8 filenames before invoking gleam\nuse std::ffi::OsStr;\nfn all_utf8(dir: &Path) -> bool {\n    walkdir::WalkDir::new(dir).into_iter().all(|e| {\n        e.map(|e| e.file_name().to_str().is_some()).unwrap_or(true)\n    })\n}","typeGuard":"fn is_utf8_path(p: &std::path::Path) -> bool { p.to_str().is_some() }","tryCatchPattern":"std::panic::catch_unwind(|| gleam_files(&dir).collect::<Vec<_>>())\n    .map_err(|_| anyhow!(\"project contains a non-UTF-8 filename\"))?","preventionTips":["Keep only ASCII-lowercase module files inside src/ and test/.","Set a UTF-8 locale (LANG=C.UTF-8) on Linux so new files get valid names.","Extract archives with encoding-correct tools and verify filenames before adding them to the project.","Add a CI check that fails when any source-tree filename is not valid UTF-8."],"tags":["filesystem","encoding","utf-8","panic"],"backgroundTag":"non-utf8-path","analyzedSha":"15b07c783065c92bb016b1b74ed0995a5259850f","analyzedAt":"2026-09-14T11:14:59.388Z","contentChangedAt":"2026-09-14T11:14:59.388Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}