getzola/zola · error

Project root dir is not valid UTF-8.

Error message

Project root dir is not valid UTF-8.

What it means

serve() converts the project root directory Path to a &str via to_str().expect(...) so it can be embedded in URLs and watch paths. The expect fires when the path contains bytes that are not valid UTF-8 (e.g. non-UTF8 filesystem names on Unix), meaning the dev server cannot represent the project location as a string and refuses to start rather than serving from a mis-encoded path.

Source

Thrown at src/cmd/serve.rs:567

        config_file,
        include_drafts,
        store_html,
        no_port_append,
    )?;
    let base_path = match constructed_base_url.splitn(4, '/').nth(3) {
        Some(path) => format!("/{path}"),
        None => "/".to_string(),
    };

    messages::report_elapsed_time(start);

    // Stop right there if we can't bind to the address
    if (TcpListener::bind(bind_address)).is_err() {
        return Err(anyhow!("Cannot start server on address {}.", bind_address));
    }

    let config_path = PathBuf::from(config_file);
    let root_dir_str = root_dir.to_str().expect("Project root dir is not valid UTF-8.");

    // An array of (path, WatchMode, RecursiveMode) where the path is watched for changes,
    // the WatchMode value indicates whether this path must exist for zola serve to operate,
    // and the RecursiveMode value indicates whether to watch nested directories.
    let mut watch_this = vec![
        // The first entry is ultimately to watch config.toml in a more robust manner on Linux when
        // the file changes by way of a caching strategy used by editors such as vim.
        // https://github.com/getzola/zola/issues/2266
        (root_dir_str, WatchMode::Required, RecursiveMode::NonRecursive),
        ("content", WatchMode::Required, RecursiveMode::Recursive),
        ("sass", WatchMode::Condition(site.config.compile_sass), RecursiveMode::Recursive),
        ("static", WatchMode::Optional, RecursiveMode::Recursive),
        ("templates", WatchMode::Optional, RecursiveMode::Recursive),
        ("themes", WatchMode::Condition(site.config.theme.is_some()), RecursiveMode::Recursive),
    ];
    watch_this.extend(
        extra_watch_paths
            .iter()

View on GitHub (pinned to 61d3082821)

Solutions

1. Rename the project directory so its full path contains only valid UTF-8 characters
2. Avoid non-ASCII or raw-byte characters in directory names on the affected filesystem
3. Return a proper anyhow error with the path's Debug representation instead of expect(), so the offending path is visible to the user

When it happens

Trigger: Thrown at src/cmd/serve.rs:567 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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