getzola/zola · error

Config name is not valid UTF-8.

Error message

Config name is not valid UTF-8.

What it means

Inside the server thread, serve() turns the config file path into a string to hand to the file watcher (the config's parent directory is monitored for reloads). The conversion fails when the config path is not valid UTF-8, so the watcher cannot be set up for the config file and live-reload of config changes would silently not work; the expect aborts the thread to make the incompatibility explicit.

Source

Thrown at src/cmd/serve.rs:672

            log::info!(
                "Web server is available at {} (bound to {})\n",
                constructed_base_url.replace(&bind_address.to_string(), &local_addr.to_string()),
                local_addr
            );
            if open && let Err(err) = open::that(&constructed_base_url) {
                log::error!("Failed to open URL in your browser: {err}");
            }

            axum::serve(listener, app).await.expect("Could not start web server");
        });
    });

    // We watch for changes in the config by monitoring its parent directory, but we ignore all
    // ordinary peer files. Map the parent directory back to the config file name to not confuse
    // the end user.
    let config_name =
        config_path.file_name().unwrap().to_str().expect("Config name is not valid UTF-8.");
    let watch_list = watchers
        .iter()
        .map(|w| if w == root_dir_str { config_name } else { w })
        .collect::<Vec<&str>>()
        .join(",");
    log::info!(
        "Listening for changes in {}{}{{{}}}",
        root_dir.display(),
        MAIN_SEPARATOR,
        watch_list
    );

    let preserve_dotfiles_in_output = site.config.preserve_dotfiles_in_output;

    log::info!("Press Ctrl+C to stop\n");
    // Clean the output folder on ctrl+C
    ctrlc::set_handler(move || {
        match clean_site_output_folder(&output_path, preserve_dotfiles_in_output) {

View on GitHub (pinned to 61d3082821)

Solutions

1. Rename the config file (and its parent directories) to use only valid UTF-8 characters
2. Pass the path to the watcher as OsStr/Path bytes instead of converting to str
3. Return a descriptive error naming the offending path instead of expect()

When it happens

Trigger: Thrown at src/cmd/serve.rs:672 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/19091e8aed7bbc27. Report an issue: GitHub.