block/buzz · critical

Configuration error: {e}

Error message

Configuration error: {e}

What it means

Fatal startup error from buzz-relay's main(): Config::from_env() could not turn the process environment into a valid Config. The precise cause is logged one line earlier as `Invalid configuration: {e}` (which variable failed and why); this anyhow error then propagates and terminates the process before any listener binds.

Source

Thrown at crates/buzz-relay/src/main.rs:154

        )
        .with(otel_layer.map(|layer| {
            layer.with_filter(telemetry::otel_env_filter(
                std::env::var("BUZZ_OTEL_FILTER").ok().as_deref(),
            ))
        }))
        .with(trace_context_lookup_layer)
        .init();

    // Log any exporter-build failure now that the subscriber is installed.
    if let telemetry::TracerInit::ExporterBuildFailed(ref e) = tracer_init {
        warn!(error = %e, "Failed to build OTLP trace exporter; distributed tracing disabled");
    }

    info!("Starting buzz-relay");

    let config = Config::from_env().map_err(|e| {
        error!("Invalid configuration: {e}");
        anyhow::anyhow!("Configuration error: {e}")
    })?;
    let relay_keypair = relay_keypair_from_config(config.relay_private_key.as_deref())?;
    info!(
        bind_addr = %config.bind_addr,
        relay_url = %config.relay_url,
        health_port = config.health_port,
        metrics_port = config.metrics_port,
        max_frame_bytes = config.max_frame_bytes,
        audit_enabled = config.audit_enabled,
        push_enabled = config.push_enabled,
        "Config loaded"
    );

    let usage_interval_secs = usage_metrics_interval_secs();
    let usage_idle_timeout_secs = usage_metrics_idle_timeout_secs(usage_interval_secs);
    relay_metrics::install(config.metrics_port, usage_idle_timeout_secs);
    metrics::gauge!("buzz_audit_enabled").set(if config.audit_enabled { 1.0 } else { 0.0 });
    metrics::gauge!("buzz_push_enabled").set(if config.push_enabled { 1.0 } else { 0.0 });

View on GitHub (pinned to eed74bde2f)

Solutions

1. Read the `Invalid configuration: {e}` log line immediately above the error — it names the offending variable and the reason
2. Diff your .env against .env.example and fix the named variable
3. Unset the variable entirely if you want the built-in default instead of an empty/invalid string
4. Restart the relay after correcting the environment

Example fix

# before (.env)
BUZZ_RELAY_URL=localhost:3000
BUZZ_DB_POOL_SIZE=ten

# after (.env)
BUZZ_RELAY_URL=ws://localhost:3000
BUZZ_DB_POOL_SIZE=10

# Preflight in deploy scripts / CI:
# docker run --rm --env-file .env buzz-relay config-check 2>&1 | grep 'Invalid configuration'
# or run the binary with a no-op entrypoint that constructs Config::from_env()
# and fails before binding anything.

When it happens

Trigger: Starting buzz-relay with a malformed DATABASE_URL / REDIS_URL / BUZZ_RELAY_URL, a non-numeric value in a numeric var (pool sizes, ports, intervals), an out-of-range number, or an invalid enum value for a toggled option.

Common situations: Hand-edited .env with a typo; copying .env.example but leaving placeholder text in a URL; CI injecting an empty string into a var the code treats as present-but-invalid; a release changing a var's expected format.

Related errors

• RELAY_OWNER_PUBKEY required when BUZZ_REQUIRE_RELAY_MEMBERSH
• BUZZ_RELAY_PRIVATE_KEY is required when BUZZ_REQUIRE_RELAY_M
• Cannot derive a community host from BUZZ_RELAY_URL ({:?}); a
• Redis pool creation failed: {e}
• invalid media config: {e}

AI-assisted analysis of block/buzz@eed74bde2f (2026-08-30). Data as JSON: /api/errors/992f6c4f518f558e. Report an issue: GitHub.