tauri-apps/tauri · error · std::io::Error

Non-UTF-8 path: {rel_path:?}

Error message

Non-UTF-8 path: {rel_path:?}

What it means

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.

Source

Thrown at crates/tauri-bundler/src/bundle/linux/debian.rs:320

fn generate_md5sums(control_dir: &Path, data_dir: &Path) -> crate::Result<()> {
  let md5sums_path = control_dir.join("md5sums");
  let mut md5sums_file = fs_utils::create_file(&md5sums_path)?;
  for entry in WalkDir::new(data_dir) {
    let entry = entry?;
    let path = entry.path();
    if path.is_dir() {
      continue;
    }
    let mut file = File::open(path)?;
    let mut hash = md5::Context::new();
    io::copy(&mut file, &mut hash)?;
    for byte in hash.finalize().iter() {
      write!(md5sums_file, "{byte:02x}")?;
    }
    let rel_path = path.strip_prefix(data_dir)?;
    let path_str = rel_path.to_str().ok_or_else(|| {
      let msg = format!("Non-UTF-8 path: {rel_path:?}");
      io::Error::new(io::ErrorKind::InvalidData, msg)
    })?;
    writeln!(md5sums_file, "  {path_str}")?;
  }
  Ok(())
}

/// Copy the bundle's resource files into an appropriate directory under the
/// `data_dir`.
fn copy_resource_files(settings: &Settings, data_dir: &Path) -> crate::Result<()> {
  let resource_dir = data_dir.join("usr/lib").join(settings.product_name());
  settings.copy_resources(&resource_dir)
}

/// Create an empty file at the given path, creating any parent directories as
/// needed, then write `data` into the file.
fn create_file_with_data<P: AsRef<Path>>(path: P, data: &str) -> crate::Result<()> {
  let mut file = fs_utils::create_file(path.as_ref())?;
  file.write_all(data.as_bytes())?;

View on GitHub (pinned to 52e4b6e71d)

Solutions

1. 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
2. Rename the file to an ASCII/UTF-8 name in your resources directory and update any references to it
3. Exclude the file from `bundle.resources` in tauri.conf.json if it is not needed at runtime
4. If the file is generated by a build step, fix that step to emit UTF-8 filenames

Example fix

# before: resources dir holds a file whose name is Latin-1 bytes (caf\xe9.png)
python3 -c "import os,sys
for r,_,fs in os.walk(b'src-tauri/resources'):
    for n in fs:
        try: n.decode('utf-8')
        except UnicodeDecodeError: sys.exit(f'non-UTF-8 filename: {r}/{n!r}')"
# after: rename to ASCII, rebuild
mv src-tauri/resources/caf$'\xe9'.png src-tauri/resources/cafe.png

# pre-build gate: abort before `tauri build` if any bundled path is not UTF-8
python3 - <<'EOF'
import os, sys
for root, _, files in os.walk(b"src-tauri/resources"):
    for name in files:
        try:
            name.decode("utf-8")
        except UnicodeDecodeError:
            sys.exit(f"non-UTF-8 filename: {os.path.join(root, name)!r}")
EOF

When it happens

Trigger: 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()`.

Common situations: 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.

Related errors

• failed to read resource folder name
• No matching IconType
• failed to read external binary path
• failed to read binary path
• failed to convert merge module filename to string

AI-assisted analysis of tauri-apps/tauri@52e4b6e71d (2026-08-20). Data as JSON: /api/errors/6c4d7f9533def2bf. Report an issue: GitHub.