{"record":{"id":"796241603d5ef5c3","repo":"rust-lang/cargo","slug":"cannot-package-a-filename-with-a-special-character","errorCode":null,"errorMessage":"cannot package a filename with a special character `{}`: {}","messagePattern":"cannot package a filename with a special character `(.+?)`: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/ops/cargo_package/mod.rs","lineNumber":1106,"sourceCode":"// 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()\n        ))?;\n    }\n    Ok(())\n}\n\n/// Manages a temporary local registry that we use to overlay our new packages on the\n/// upstream registry. This way we can build lockfiles that depend on the new packages even\n/// before they're published.","sourceCodeStart":1088,"sourceCodeEnd":1124,"githubUrl":"https://github.com/rust-lang/cargo/blob/495c385d0875c4ba51eb72ea0448a2d4c018b8d4/src/ops/cargo_package/mod.rs#L1088-L1124","documentation":"Thrown by `check_filename` during `cargo package` when a filename contains one of the reserved special characters: `/ \\ < > : \" | ? *`. These characters are invalid in Windows filenames and would make the package fail to extract on that platform.","triggerScenarios":"Running `cargo package` when any file in the source tree contains one of `/'\\<>:\\\"|?*` in its name. The check iterates `bad_chars` and bails on the first match.","commonSituations":"Files with colons in names (common in Unix backup tools like `2024-01-01:backup`); files with quotes or angle brackets created by other tooling; accidentally committed log files with timestamps containing colons.","solutions":["Rename the file to remove the special character.","Remove the file from the source tree.","Add the file path to the `exclude` list in Cargo.toml `[package]` section."],"exampleFix":"# Rename the offending file\nmv \"log:2024.txt\" log-2024.txt","handlingStrategy":"validation","validationCode":"use std::path::Path;\nfn check_filenames_no_special_chars(root: &Path) -> Result<(), String> {\n    let bad = ['/', '\\\\', '<', '>', ':', '\"', '|', '?', '*'];\n    for entry in walkdir::WalkDir::new(root) {\n        let entry = entry.map_err(|e| e.to_string())?;\n        if let Some(name) = entry.file_name().to_str() {\n            if let Some(c) = bad.iter().find(|c| name.contains(**c)) {\n                return Err(format!(\"filename `{}` contains special char `{}`\", name, c));\n            }\n        }\n    }\n    Ok(())\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never use `:`, `*`, `?`, `<`, `>`, `|`, `\"`, or `\\` in source file names.","Replace colons in timestamped filenames with dashes.","Test packaging on both Unix and Windows if cross-platform support is needed."],"tags":["cargo-package","filename","windows","cross-platform","special-chars"],"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"}