Hmbown/CodeWhale · critical · anyhow::Error

refusing non-loopback app-server bind without explicit auth…

Error message

refusing non-loopback app-server bind without explicit auth token; pass --auth-token or set CODEWHALE_APP_SERVER_TOKEN

What it means

When the app-server binds to a non-loopback address, an explicit authentication token is mandatory. If no token was configured via `--auth-token` or `CODEWHALE_APP_SERVER_TOKEN`, startup is aborted rather than silently running an unauthenticated network listener. This pairs with the insecure-no-auth guard to ensure any non-local bind is authenticated.

Solutions

Set `CODEWHALE_APP_SERVER_TOKEN` to a strong random value in the deployment environment.
Pass `--auth-token <token>` on the command line.
Bind to 127.0.0.1 if the client is only ever local.

Example fix

// before (docker-compose)
command: ["app-server", "--listen", "0.0.0.0:3927"]
// after
environment:
  - CODEWHALE_APP_SERVER_TOKEN=${APP_SERVER_TOKEN}
command: ["app-server", "--listen", "0.0.0.0:3927"]

Defensive patterns

Strategy: validation

Validate before calling

// before launching, fail fast if the token is missing for non-loopback binds
if !listen.is_loopback() && std::env::var("CODEWHALE_APP_SERVER_TOKEN").map_or(true, |t| t.is_empty()) {
    return Err("set CODEWHALE_APP_SERVER_TOKEN before binding non-loopback".into());
}

Prevention

Set CODEWHALE_APP_SERVER_TOKEN in every non-local deployment (compose/k8s/CI) as a required secret.
Generate tokens with a CSPRNG (e.g. openssl rand -hex 32).
Add a startup smoke test that asserts the server stays up with the given flags.

When it happens

Trigger: Starting the app-server with a non-loopback `--listen` address while neither `--auth-token` is passed nor `CODEWHALE_APP_SERVER_TOKEN` is set in the environment.

Common situations: Deploying the app-server in Docker/Kubernetes or on a remote host and forgetting to set the token env var in the service definition; CI containers binding 0.0.0.0 without credentials.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/d93e9ececf7513b6. Report an issue: GitHub.

Appendix: source

Thrown at crates/app-server/src/lib.rs:889

fn resolve_auth_token(options: &AppServerOptions) -> Result<Option<String>> {
    let configured = options.auth_token.as_ref().map(|token| token.trim());
    if let Some(token) = configured
        && token.is_empty()
    {
        bail!("app-server auth token cannot be empty");
    }
    let has_explicit_token = configured.is_some();

    if options.insecure_no_auth {
        if !options.listen.ip().is_loopback() {
            bail!("refusing unauthenticated app-server bind on non-loopback address");
        }
        eprintln!("warning: app-server HTTP auth disabled by --insecure-no-auth");
        return Ok(None);
    }

    if !has_explicit_token && !options.listen.ip().is_loopback() {
        bail!(
            "refusing non-loopback app-server bind without explicit auth token; pass --auth-token or set CODEWHALE_APP_SERVER_TOKEN"
        );
    }

    let token = configured
        .map(str::to_string)
        .unwrap_or_else(|| format!("cwapp_{}", Uuid::new_v4().simple()));
    for line in app_server_auth_status_lines(has_explicit_token) {
        eprintln!("{line}");
    }
    Ok(Some(token))
}

fn app_server_auth_status_lines(has_explicit_token: bool) -> Vec<&'static str> {
    if has_explicit_token {
        return vec!["app-server auth: bearer token required for HTTP routes."];
    }
    vec![

View on GitHub (pinned to 73e0f67d83)