What causes "Cannot start server on address {}." in getzola/zola?

Use a different port: zola serve -p 2222

Cannot start server on address {}.

Error message

Cannot start server on address {}.

What it means

The serve command binds a TCP listener to the requested address/port after building the site; if the bind fails (address in use, port privileged, interface unavailable), serve aborts with this error naming the bind address.

Source

Thrown at src/cmd/serve.rs:563

        interface_port,
        output_dir,
        force,
        base_url,
        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),

View on GitHub (pinned to 61d3082821)

Solutions

Use a different port: zola serve -p 2222
Find and stop the process already bound to the port (lsof -i :1111 / netstat)
Use a valid local interface address, or 127.0.0.1 explicitly
On Linux, allow unprivileged binding to low ports (sysctl net.ipv4.ip_unprivileged_port_start) or run with privileges

Example fix

// before
zola serve -p 1111   // Error: Cannot start server on address 127.0.0.1:1111
// after
zola serve -p 1112

Defensive patterns

Strategy: validation

Validate before calling

// Check the port is free before serving:
// if lsof -i :1111 >/dev/null 2>&1; then echo "port busy"; else zola serve; fi

Try / catch

// shell
zola serve -p 1111 || { echo "serve failed; trying 1112"; zola serve -p 1112; }

Prevention

Pick an uncommon default port for your team to avoid clashes
Kill stale zola serve processes before starting a new one
Avoid privileged ports (<1024) unless running as root or with CAP_NET_BIND_SERVICE

When it happens

Trigger: Running zola serve -a ADDRESS -p PORT where the port is already occupied by another process, the address is not a local interface, or the port is <1024 without privileges.

Common situations: Another zola serve instance still running on the default port 1111; a dev server from another project on the same port; picking port 80/443 without root; typos in the interface address.

Related errors

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