{"record":{"id":"6c4d7f9533def2bf","repo":"tauri-apps/tauri","slug":"non-utf-8-path-rel-path","errorCode":null,"errorMessage":"Non-UTF-8 path: {rel_path:?}","messagePattern":"Non-UTF-8 path: (.+?)","errorType":"exception","errorClass":"std::io::Error","httpStatus":null,"severity":"error","filePath":"crates/tauri-bundler/src/bundle/linux/debian.rs","lineNumber":320,"sourceCode":"fn generate_md5sums(control_dir: &Path, data_dir: &Path) -> crate::Result<()> {\n  let md5sums_path = control_dir.join(\"md5sums\");\n  let mut md5sums_file = fs_utils::create_file(&md5sums_path)?;\n  for entry in WalkDir::new(data_dir) {\n    let entry = entry?;\n    let path = entry.path();\n    if path.is_dir() {\n      continue;\n    }\n    let mut file = File::open(path)?;\n    let mut hash = md5::Context::new();\n    io::copy(&mut file, &mut hash)?;\n    for byte in hash.finalize().iter() {\n      write!(md5sums_file, \"{byte:02x}\")?;\n    }\n    let rel_path = path.strip_prefix(data_dir)?;\n    let path_str = rel_path.to_str().ok_or_else(|| {\n      let msg = format!(\"Non-UTF-8 path: {rel_path:?}\");\n      io::Error::new(io::ErrorKind::InvalidData, msg)\n    })?;\n    writeln!(md5sums_file, \"  {path_str}\")?;\n  }\n  Ok(())\n}\n\n/// Copy the bundle's resource files into an appropriate directory under the\n/// `data_dir`.\nfn copy_resource_files(settings: &Settings, data_dir: &Path) -> crate::Result<()> {\n  let resource_dir = data_dir.join(\"usr/lib\").join(settings.product_name());\n  settings.copy_resources(&resource_dir)\n}\n\n/// Create an empty file at the given path, creating any parent directories as\n/// needed, then write `data` into the file.\nfn create_file_with_data<P: AsRef<Path>>(path: P, data: &str) -> crate::Result<()> {\n  let mut file = fs_utils::create_file(path.as_ref())?;\n  file.write_all(data.as_bytes())?;","sourceCodeStart":302,"sourceCodeEnd":338,"githubUrl":"https://github.com/tauri-apps/tauri/blob/52e4b6e71d8632a7e648f866c442e287ecddee34/crates/tauri-bundler/src/bundle/linux/debian.rs#L302-L338","documentation":"While assembling a Debian package, the Tauri bundler writes an md5sums control file that lists every bundled file's MD5 hash and its path relative to the data directory. Debian control files are plain UTF-8 text, so a relative path containing invalid UTF-8 bytes cannot be serialized. The bundler therefore aborts with io::ErrorKind::InvalidData, echoing the offending path, instead of writing a corrupt md5sums entry.","triggerScenarios":"Running `tauri build` with the deb bundle target when any file copied into the deb data directory (resources, binaries, icons, license files) has a filename that is not valid UTF-8. The error surfaces at the md5sums generation step, after all files have already been copied into data_dir, via `let rel_path = path.strip_prefix(data_dir)?` failing `.to_str()`.","commonSituations":"Resource directories containing files created under non-UTF-8 locales (e.g. Latin-1 byte names on Windows or older Linux), assets extracted from archives that preserve raw byte filenames, or files produced by external tools with locale-dependent names. Rare on macOS, common when copying assets from untrusted or cross-platform sources.","solutions":["Locate the offending file before the copy step, e.g. with a Python walk that tries name.decode('utf-8') over src-tauri/resources and prints the failing path","Rename the file to an ASCII/UTF-8 name in your resources directory and update any references to it","Exclude the file from `bundle.resources` in tauri.conf.json if it is not needed at runtime","If the file is generated by a build step, fix that step to emit UTF-8 filenames"],"exampleFix":"# before: resources dir holds a file whose name is Latin-1 bytes (caf\\xe9.png)\npython3 -c \"import os,sys\nfor r,_,fs in os.walk(b'src-tauri/resources'):\n    for n in fs:\n        try: n.decode('utf-8')\n        except UnicodeDecodeError: sys.exit(f'non-UTF-8 filename: {r}/{n!r}')\"\n# after: rename to ASCII, rebuild\nmv src-tauri/resources/caf$'\\xe9'.png src-tauri/resources/cafe.png","handlingStrategy":"validation","validationCode":"# pre-build gate: abort before `tauri build` if any bundled path is not UTF-8\npython3 - <<'EOF'\nimport os, sys\nfor root, _, files in os.walk(b\"src-tauri/resources\"):\n    for name in files:\n        try:\n            name.decode(\"utf-8\")\n        except UnicodeDecodeError:\n            sys.exit(f\"non-UTF-8 filename: {os.path.join(root, name)!r}\")\nEOF","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep bundled resource filenames ASCII","Normalize filenames when copying assets from archives or other operating systems","Run the UTF-8 filename check as a CI step before tauri build"],"tags":["debian","bundler","utf-8","filepath","md5sums"],"backgroundTag":"non-utf8-filename","analyzedSha":"52e4b6e71d8632a7e648f866c442e287ecddee34","analyzedAt":"2026-08-20T13:59:20.734Z","contentChangedAt":"2026-08-20T13:59:20.734Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}