What causes "Could not convert filename to &str" in getzola/zola?

Rename or remove the non-UTF-8 file in the target directory

Could not convert filename to &str

Error message

Could not convert filename to &str

What it means

is_directory_quasi_empty iterates directory entries and converts each file_name OsString to &str with .expect, panicking if a filename is not valid UTF-8. On Unix filenames are arbitrary bytes, so any non-UTF-8 entry in the target directory aborts `zola init`.

Source

Thrown at src/cmd/init.rs:52

// This is a workaround until this issue https://github.com/rust-lang/rust/issues/42869 was fixed.
const LOCAL_UNC: &str = "\\\\?\\";

// Given a path, return true if it is a directory and it doesn't have any
// non-hidden files, otherwise return false (path is assumed to exist)
pub fn is_directory_quasi_empty(path: &Path) -> Result<bool> {
    if path.is_dir() {
        let mut entries = match path.read_dir() {
            Ok(entries) => entries,
            Err(e) => {
                bail!("Could not read `{}` because of error: {}", path.to_string_lossy(), e);
            }
        };
        // If any entry raises an error or isn't hidden (i.e. starts with `.`), we raise an error
        if entries.any(|x| match x {
            Ok(file) => !file
                .file_name()
                .to_str()
                .expect("Could not convert filename to &str")
                .starts_with('.'),
            Err(_) => true,
        }) {
            return Ok(false);
        }
        return Ok(true);
    }

    Ok(false)
}

// Remove the unc part of a windows path
fn strip_unc(path: &Path) -> String {
    let path_to_refine = path.to_str().unwrap();
    path_to_refine.trim_start_matches(LOCAL_UNC).to_string()
}

pub fn create_new_project(name: &str, force: bool) -> Result<()> {

View on GitHub (pinned to 61d3082821)

Solutions

Rename or remove the non-UTF-8 file in the target directory
Use to_string_lossy() instead of to_str().expect() so odd names are treated as visible (non-hidden) entries
Pre-validate the directory with a script that lists non-UTF-8 names (e.g. `find . | grep -P '[^\x00-\x7F]'`)

Example fix

// before
Ok(file) => !file
    .file_name()
    .to_str()
    .expect("Could not convert filename to &str")
    .starts_with('.'),
// after
Ok(file) => !file
    .file_name()
    .to_string_lossy()
    .starts_with('.'),

Defensive patterns

Strategy: validation

Validate before calling

// before running zola init, check for non-UTF-8 filenames
use std::ffi::OsStr;
use std::os::unix::ffi::OsStrExt;
for entry in std::fs::read_dir(".")? {
    let name = entry?.file_name();
    if std::str::from_utf8(name.as_bytes()).is_err() {
        eprintln!("non-UTF-8 filename: {:?}", name);
    }
}

Type guard

fn is_utf8_name(name: &std::ffi::OsStr) -> bool {
    use std::os::unix::ffi::OsStrExt;
    std::str::from_utf8(name.as_bytes()).is_ok()
}

Prevention

Use to_string_lossy() when only a heuristic check (hidden-file detection) is needed
Avoid extracting archives with legacy encodings into the target directory
Normalize filenames to UTF-8 before pointing tools at a directory

When it happens

Trigger: Running `zola init` in (or pointing init at) a directory containing a file whose name is not valid UTF-8, e.g. created by tools using legacy encodings or raw bytes.

Common situations: Projects synced from Windows/macOS with unusual names, files created by other programs with byte-level names, extracted archives with latin-1 filenames.

Related errors

AI-assisted analysis of getzola/zola@61d3082821 (2026-09-03). Data as JSON: /api/errors/dc094a4c545a3f7f. Report an issue: GitHub.