{"record":{"id":"5fb95cf39e97b13f","repo":"getzola/zola","slug":"cannot-start-server-on-address","errorCode":null,"errorMessage":"Cannot start server on address {}.","messagePattern":"Cannot start server on address (.+?)\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cmd/serve.rs","lineNumber":563,"sourceCode":"        interface_port,\n        output_dir,\n        force,\n        base_url,\n        config_file,\n        include_drafts,\n        store_html,\n        no_port_append,\n    )?;\n    let base_path = match constructed_base_url.splitn(4, '/').nth(3) {\n        Some(path) => format!(\"/{path}\"),\n        None => \"/\".to_string(),\n    };\n\n    messages::report_elapsed_time(start);\n\n    // Stop right there if we can't bind to the address\n    if (TcpListener::bind(bind_address)).is_err() {\n        return Err(anyhow!(\"Cannot start server on address {}.\", bind_address));\n    }\n\n    let config_path = PathBuf::from(config_file);\n    let root_dir_str = root_dir.to_str().expect(\"Project root dir is not valid UTF-8.\");\n\n    // An array of (path, WatchMode, RecursiveMode) where the path is watched for changes,\n    // the WatchMode value indicates whether this path must exist for zola serve to operate,\n    // and the RecursiveMode value indicates whether to watch nested directories.\n    let mut watch_this = vec![\n        // The first entry is ultimately to watch config.toml in a more robust manner on Linux when\n        // the file changes by way of a caching strategy used by editors such as vim.\n        // https://github.com/getzola/zola/issues/2266\n        (root_dir_str, WatchMode::Required, RecursiveMode::NonRecursive),\n        (\"content\", WatchMode::Required, RecursiveMode::Recursive),\n        (\"sass\", WatchMode::Condition(site.config.compile_sass), RecursiveMode::Recursive),\n        (\"static\", WatchMode::Optional, RecursiveMode::Recursive),\n        (\"templates\", WatchMode::Optional, RecursiveMode::Recursive),\n        (\"themes\", WatchMode::Condition(site.config.theme.is_some()), RecursiveMode::Recursive),","sourceCodeStart":545,"sourceCodeEnd":581,"githubUrl":"https://github.com/getzola/zola/blob/61d30828217957120309db657950224edf9707e2/src/cmd/serve.rs#L545-L581","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nzola serve -p 1111   // Error: Cannot start server on address 127.0.0.1:1111\n// after\nzola serve -p 1112","handlingStrategy":"validation","validationCode":"// Check the port is free before serving:\n// if lsof -i :1111 >/dev/null 2>&1; then echo \"port busy\"; else zola serve; fi","typeGuard":null,"tryCatchPattern":"// shell\nzola serve -p 1111 || { echo \"serve failed; trying 1112\"; zola serve -p 1112; }","preventionTips":["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"],"tags":["rust","server","port-binding"],"backgroundTag":"address-in-use","analyzedSha":"61d30828217957120309db657950224edf9707e2","analyzedAt":"2026-09-03T14:39:09.727Z","contentChangedAt":"2026-09-03T14:39:09.727Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}