{"record":{"id":"1c13e9bfe9724a93","repo":"rust-lang/cargo","slug":"path-does-not-have-a-unicode-filename-which-may-no","errorCode":null,"errorMessage":"path does not have a unicode filename which may not unpack on all platforms: {}","messagePattern":"path does not have a unicode filename which may not unpack on all platforms: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/ops/cargo_package/mod.rs","lineNumber":1098,"sourceCode":"        .collect::<FuturesUnordered<_>>();\n    crate::util::block_on(async {\n        while futures.try_next().await?.is_some() {}\n        CargoResult::Ok(())\n    })\n}\n\n// It can often be the case that files of a particular name on one platform\n// can't actually be created on another platform. For example files with colons\n// in the name are allowed on Unix but not on Windows.\n//\n// To help out in situations like this, issue about weird filenames when\n// packaging as a \"heads up\" that something may not work on other platforms.\nfn check_filename(file: &Path, shell: &mut Shell) -> CargoResult<()> {\n    let Some(name) = file.file_name() else {\n        return Ok(());\n    };\n    let Some(name) = name.to_str() else {\n        anyhow::bail!(\n            \"path does not have a unicode filename which may not unpack \\\n             on all platforms: {}\",\n            file.display()\n        )\n    };\n    let bad_chars = ['/', '\\\\', '<', '>', ':', '\"', '|', '?', '*'];\n    if let Some(c) = bad_chars.iter().find(|c| name.contains(**c)) {\n        anyhow::bail!(\n            \"cannot package a filename with a special character `{}`: {}\",\n            c,\n            file.display()\n        )\n    }\n    if restricted_names::is_windows_reserved_path(file) {\n        shell.warn(format!(\n            \"file {} is a reserved Windows filename, \\\n                it will not work on Windows platforms\",\n            file.display()","sourceCodeStart":1080,"sourceCodeEnd":1116,"githubUrl":"https://github.com/rust-lang/cargo/blob/495c385d0875c4ba51eb72ea0448a2d4c018b8d4/src/ops/cargo_package/mod.rs#L1080-L1116","documentation":"Thrown by `check_filename` during `cargo package` when a file in the source tree has a filename that cannot be converted to a Unicode string (`to_str()` returns `None`). Such files may fail to unpack on other platforms. This is a cross-platform portability guard.","triggerScenarios":"Running `cargo package` on a workspace containing a file whose name includes bytes that are not valid UTF-8 (possible on Unix where filenames are byte strings). The `file.file_name()` succeeds but `.to_str()` returns `None`.","commonSituations":"Files created by other tools or filesystems that use non-UTF-8 byte sequences in names; files carried over from legacy systems; git checkouts on Unix that preserved non-UTF-8 names.","solutions":["Rename the file to use only valid UTF-8 characters.","Remove the file from the package source tree if it is not needed.","Add it to `.cargoignore` or exclude it via the `exclude` key in Cargo.toml."],"exampleFix":"# Rename on Unix\nmv \"$(printf 'bad\\xffname.txt')\" goodname.txt","handlingStrategy":"validation","validationCode":"use std::path::Path;\nfn check_all_filenames_unicode(root: &Path) -> Result<(), String> {\n    for entry in walkdir::WalkDir::new(root) {\n        let entry = entry.map_err(|e| e.to_string())?;\n        if entry.file_name().to_str().is_none() {\n            return Err(format!(\"non-unicode filename: {}\", entry.path().display()));\n        }\n    }\n    Ok(())\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Avoid creating files with non-UTF-8 names on any platform.","Run `cargo package` locally to catch problematic filenames before CI.","Use `.gitignore` or Cargo.toml `exclude` to skip problematic files."],"tags":["cargo-package","filename","unicode","cross-platform"],"backgroundTag":null,"analyzedSha":"495c385d0875c4ba51eb72ea0448a2d4c018b8d4","analyzedAt":"2026-08-11T17:42:36.556Z","contentChangedAt":"2026-08-11T17:42:36.556Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}