What causes "Port must be > 0" in Hmbown/CodeWhale?

Pass an explicit port greater than 0 (e.g. --port 8080 or RuntimeApiOptions { port: 8080, .. }).

Port must be > 0

Error message

Port must be > 0

What it means

run_http_server validates RuntimeApiOptions before binding and rejects port == 0. Unlike some servers that treat 0 as 'assign me an ephemeral port', the runtime API requires an explicit positive port because clients (web UI, bridges) must know the port ahead of time. The field is a u16, so only the value 0 fails this check.

Source

Thrown at crates/tui/src/runtime_api.rs:832

    let workshop_activation = install_runtime_server_workshop_budgets(config);
    let manager = Arc::new(RuntimeThreadManager::open_with_plugin_registry(
        config.clone(),
        workspace,
        manager_config,
        plugin_registry,
    )?);
    Ok((manager, workshop_activation))
}

/// Start the runtime API server.
pub async fn run_http_server(
    config: Config,
    workspace: PathBuf,
    plugin_discovery: Arc<crate::plugins::PluginDiscoveryContext>,
    options: RuntimeApiOptions,
) -> Result<()> {
    if options.port == 0 {
        bail!("Port must be > 0");
    }
    if options.web && options.host != "127.0.0.1" {
        bail!("Codewhale web is loopback-only and must bind to 127.0.0.1");
    }
    if options.web && options.insecure_no_auth {
        bail!("Codewhale web requires Runtime authentication; remove --insecure");
    }

    let task_cfg = TaskManagerConfig::from_runtime(
        &config,
        workspace.clone(),
        config.default_text_model.clone(),
        Some(options.workers),
    );
    let (runtime_threads, _workshop_activation) = open_runtime_threads_for_server(
        &config,
        workspace.clone(),
        RuntimeThreadManagerConfig::from_task_data_dir(task_cfg.data_dir.clone()),

View on GitHub (pinned to 0c42157ee5)

Solutions

Pass an explicit port greater than 0 (e.g. --port 8080 or RuntimeApiOptions { port: 8080, .. }).
If the port comes from config, check how unset values deserialize and give the key a real default instead of 0.
Pick a port outside the ephemeral range if you also want stable reboots (e.g. avoid 32768-60999 on Linux).

Example fix

// before
let options = RuntimeApiOptions { port: 0, ..Default::default() };
run_http_server(config, workspace, discovery, options).await?; // bails: Port must be > 0

// after
let options = RuntimeApiOptions { port: 8080, ..Default::default() };
run_http_server(config, workspace, discovery, options).await?;

Defensive patterns

Strategy: validation

Validate before calling

// Rust: validate options before starting the server
fn valid_port(port: u16) -> bool { port > 0 }

let port = options.port;
anyhow::ensure!(valid_port(port), "refusing to start: port {port} must be > 0");
run_http_server(config, workspace, discovery, options).await?;

Prevention

Give the port a real non-zero default wherever RuntimeApiOptions is constructed.
Fail fast on unset config keys (Option<u16>) instead of coercing them to 0.
Log the resolved port at startup so misconfiguration is visible immediately.

When it happens

Trigger: Starting the runtime API server with RuntimeApiOptions { port: 0, .. }; typically from a CLI/server subcommand where the port flag was not provided and defaulted to 0, or a config that parsed an unset port.

Common situations: Assuming OS-assigned ephemeral ports work here; config files with port: 0 or a commented-out port that deserializes to 0; scripts copying an example that never set --port.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@0c42157ee5 (2026-08-20). Data as JSON: /api/errors/5750367b74534415. Report an issue: GitHub.