zeroclaw-labs/zeroclaw · error · anyhow::Error

Gateway feature is not enabled. Rebuild with --features gate

Error message

Gateway feature is not enabled. Rebuild with --features gateway

What it means

The binary was compiled without the `gateway` cargo feature, so run_gateway_if_enabled is the stub variant (note the underscore-prefixed unused parameters in the SOURCE) that always bails. There is no runtime gateway implementation in this build to serve HTTP/WebSocket traffic.

Source

Thrown at src/main.rs:8149

            let restart_port = available_gateway_restart_hint_port(host, port);
            anyhow::bail!(
                "{}",
                gateway_addr_in_use_message(host, port, &default_host, default_port, restart_port)
            );
        }
        other => other,
    }
}

#[cfg(not(feature = "gateway"))]
#[allow(clippy::unused_async)]
async fn run_gateway_if_enabled(
    _host: &str,
    _port: u16,
    _config: zeroclaw::config::Config,
    _tx: Option<tokio::sync::broadcast::Sender<serde_json::Value>>,
) -> anyhow::Result<()> {
    anyhow::bail!("Gateway feature is not enabled. Rebuild with --features gateway")
}

fn is_addr_in_use_error(err: &anyhow::Error) -> bool {
    err.chain().any(|cause| {
        cause
            .downcast_ref::<std::io::Error>()
            .is_some_and(|io| io.kind() == ErrorKind::AddrInUse)
    })
}

fn is_default_gateway_addr(host: &str, port: u16, default_host: &str, default_port: u16) -> bool {
    host == default_host && port == default_port
}

fn gateway_browser_host(host: &str) -> &str {
    match host {
        "0.0.0.0" => "127.0.0.1",
        "::" | "[::]" => "[::1]",

View on GitHub (pinned to 88bb9c8533)

Solutions

Rebuild with the gateway feature: `cargo build --release --features gateway`
Verify the feature actually reached the build (check the cargo command / feature list used by your install method)
If installed via a package manager, switch to a package/build that includes the gateway feature
Avoid `--no-default-features` unless you explicitly re-add the features you need

Example fix

# before
cargo install zeroclaw
zeroclaw serve   # -> Gateway feature is not enabled

# after
cargo install zeroclaw --features gateway
zeroclaw serve

Defensive patterns

Strategy: validation

Validate before calling

// Compile-time: gate your call site the same way the crate does.
#[cfg(feature = "gateway")]
async fn serve() -> anyhow::Result<()> { run_gateway_if_enabled(...).await }
#[cfg(not(feature = "gateway"))]
compile_error!("this binary needs `--features gateway`; rebuild with it enabled");

Type guard

// Runtime feature detection for prebuilt binaries: probe for the gateway path
// cheaply (e.g. `zeroclaw --help` output or a /healthz attempt) and treat
// failure as 'feature missing' before invoking serve commands.

Prevention

Bake required features into your install command (cargo install zeroclaw --features gateway)
Record required features in the deployment docs and Dockerfile
Add a smoke test that starts the gateway in CI so a feature-stripped build fails the pipeline
Avoid --no-default-features unless you explicitly enumerate what you keep

When it happens

Trigger: Invoking any command that reaches run_gateway_if_enabled (e.g. serving via the gateway) in a build produced without `--features gateway`. Typically a default `cargo build` or a distro package built with the minimal feature set.

Common situations: Installing a minimal/default-feature build then trying to use the web dashboard or gateway API; CI building with `--no-default-features`; downstream packagers trimming features to cut compile time.

Related errors

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/2593957e8475cb48. Report an issue: GitHub.