{"record":{"id":"298f41657629dfcf","repo":"rust-lang/cargo","slug":"character-at-line-is-invalid-cargo-only-suppor","errorCode":null,"errorMessage":"Character at line {} is invalid. Cargo only supports UTF-8.","messagePattern":"Character at line (.+?) is invalid\\. Cargo only supports UTF-8\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/ops/cargo_new.rs","lineNumber":609,"sourceCode":"            VersionControl::Fossil => &self.fossil_ignore,\n            _ => &self.ignore,\n        };\n\n        ignore_items.join(\"\\n\") + \"\\n\"\n    }\n\n    /// `format_existing` is used to format the `IgnoreList` when the ignore file\n    /// already exists. It reads the contents of the given `BufRead` and\n    /// checks if the contents of the ignore list are already existing in the\n    /// file.\n    fn format_existing<T: BufRead>(&self, existing: T, vcs: VersionControl) -> CargoResult<String> {\n        let mut existing_items = Vec::new();\n        for (i, item) in existing.lines().enumerate() {\n            match item {\n                Ok(s) => existing_items.push(s),\n                Err(err) => match err.kind() {\n                    ErrorKind::InvalidData => {\n                        return Err(anyhow!(\n                            \"Character at line {} is invalid. Cargo only supports UTF-8.\",\n                            i\n                        ));\n                    }\n                    _ => return Err(anyhow!(err)),\n                },\n            }\n        }\n\n        let ignore_items = match vcs {\n            VersionControl::Hg => &self.hg_ignore,\n            VersionControl::Fossil => &self.fossil_ignore,\n            _ => &self.ignore,\n        };\n\n        let mut out = String::new();\n\n        // Fossil does not support `#` comments.","sourceCodeStart":591,"sourceCodeEnd":627,"githubUrl":"https://github.com/rust-lang/cargo/blob/98a09e7e7d62850f14e5b6132101fc1edd19a16f/src/ops/cargo_new.rs#L591-L627","documentation":"While formatting/updating an existing VCS ignore file (`.gitignore`, `.hgignore`, etc.), cargo reads it line-by-line as UTF-8. If `BufRead::lines` returns `InvalidData` (the std `Utf8Error`-mapping for non-UTF-8 bytes), cargo surfaces it naming the offending line number. Cargo only handles UTF-8 content and refuses to round-trip binary/non-UTF-8 ignore files.","triggerScenarios":"`cargo init` (or `cargo new` with VCS) in a directory whose existing `.gitignore`/`.hgignore`/`.fossil-ignore` contains non-UTF-8 bytes (e.g. a stray binary blob, latin-1 encoded content, or a corrupted file). The error fires in `format_existing` during the ignore-list merge.","commonSituations":"A pre-existing `.gitignore` written by a tool that emitted non-UTF-8 (e.g. Windows-1252 on some legacy systems). Corruption from a bad merge or file transfer. A `.gitignore` that accidentally swallowed binary content.","solutions":["Re-save the ignore file as UTF-8 (`iconv -f LATIN1 -t UTF-8 .gitignore` or open and re-save in an editor set to UTF-8).","Remove the offending non-UTF-8 bytes/lines (the error names the line number).","Delete the ignore file and let cargo regenerate it, if its existing content is not worth keeping."],"exampleFix":"# before — .gitignore contains non-UTF-8 bytes at line 12\n$ cargo init   # error: Character at line 12 is invalid. Cargo only supports UTF-8.\n\n# after\n$ iconv -f LATIN1 -t UTF-8 .gitignore -o .gitignore.utf8 && mv .gitignore.utf8 .gitignore\n$ cargo init","handlingStrategy":"validation","validationCode":"use std::fs;\nuse std::str;\nfn ignore_file_is_utf8(path: &std::path::Path) -> bool {\n    match fs::read(path) {\n        Ok(bytes) => str::from_utf8(&bytes).is_ok(),\n        Err(_) => false,\n    }\n}\n// before `cargo init`, re-encode the ignore file to UTF-8 if this returns false.","typeGuard":"fn is_utf8_ignore_file(bytes: &[u8]) -> bool { std::str::from_utf8(bytes).is_ok() }","tryCatchPattern":null,"preventionTips":["Keep `.gitignore`/`.hgignore` as UTF-8; re-encode legacy files before `cargo init`.","Avoid tools that emit non-UTF-8 into ignore files.","In scaffolding, validate ignore-file encoding and convert before invoking cargo.","Add ignore-file health checks to repo onboarding scripts."],"tags":["vcs","ignore-files","utf8","encoding","cargo-init"],"backgroundTag":null,"analyzedSha":"98a09e7e7d62850f14e5b6132101fc1edd19a16f","analyzedAt":"2026-08-11T17:42:36.556Z","contentChangedAt":"2026-08-11T17:42:36.556Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}