{"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":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"src/ops/cargo_package/mod.rs","lineNumber":1105,"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":1087,"sourceCodeEnd":1123,"githubUrl":"https://github.com/rust-lang/cargo/blob/0e07a155371a6ce88ae53a2c00df940280c09a67/src/ops/cargo_package/mod.rs#L1087-L1123","documentation":"Cargo's packaging step (cargo package / cargo publish) runs check_filename over every file that would go into the .crate archive. It rejects any filename containing one of the Windows-illegal characters `/ \\ < > : \" | ? *` because such an archive would fail to unpack on Windows. This is a cross-platform safety guard, not a Unix legality check.","triggerScenarios":"Running `cargo package` or `cargo publish` when the source tree contains a file whose name includes a reserved character (e.g. a generated asset named `report:2024.txt`, a file with `?`, or a stray `*`). The check runs in check_filename at src/ops/cargo_package/mod.rs:1105.","commonSituations":"Build/code generators that emit files with timestamps containing colons; files committed on Linux that happen to contain `:` or `*`; downstream tooling writing into the package source dir.","solutions":["Locate the offending file named in the error and rename it to remove the special character (replace `:` with `-`, etc.).","If the file is generated, add it to .gitignore / package.exclude so it is never packaged.","Regenerate the asset with a Windows-safe naming scheme and re-run `cargo package`."],"exampleFix":"// before: generated file written as\n//   src/assets/log:2024-06-01.txt\n//\n// after (generator writes Windows-safe name):\n//   src/assets/log-2024-06-01.txt\n// and in Cargo.toml:\n//   [package]\n//   exclude = [\"src/assets/raw/*\"]","handlingStrategy":"validation","validationCode":"# Before packaging, scan for Windows-illegal filename characters:\nbad='/ \\ < > : \" | ? *'\nfind src -type f -print0 | while IFS= read -r -d '' f; do\n  base=\"$(basename \"$f\")\"\n  case \"$base\" in\n    *[/'\\\\'<>\":|?*]*) echo \"BAD: $f\";;\n  esac\ndone\n# exit non-zero if any BAD lines before running cargo package","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Configure code generators to emit Windows-safe filenames (no colons, asterisks, question marks).","Add generated asset directories to package.exclude or .gitignore.","Run `cargo package --list` first and eyeball the file list for odd names."],"tags":["packaging","cross-platform","windows","filenames","publish"],"analyzedSha":"0e07a155371a6ce88ae53a2c00df940280c09a67","analyzedAt":"2026-08-06T01:46:58.334Z","schemaVersion":2}