{"record":{"id":"992f6c4f518f558e","repo":"block/buzz","slug":"configuration-error-e-992f6c","errorCode":null,"errorMessage":"Configuration error: {e}","messagePattern":"Configuration error: (.+?)","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"critical","filePath":"crates/buzz-relay/src/main.rs","lineNumber":144,"sourceCode":"        )\n        .with(otel_layer.map(|layer| {\n            layer.with_filter(telemetry::otel_env_filter(\n                std::env::var(\"BUZZ_OTEL_FILTER\").ok().as_deref(),\n            ))\n        }))\n        .with(trace_context_lookup_layer)\n        .init();\n\n    // Log any exporter-build failure now that the subscriber is installed.\n    if let telemetry::TracerInit::ExporterBuildFailed(ref e) = tracer_init {\n        warn!(error = %e, \"Failed to build OTLP trace exporter; distributed tracing disabled\");\n    }\n\n    info!(\"Starting buzz-relay\");\n\n    let config = Config::from_env().map_err(|e| {\n        error!(\"Invalid configuration: {e}\");\n        anyhow::anyhow!(\"Configuration error: {e}\")\n    })?;\n    info!(\n        bind_addr = %config.bind_addr,\n        relay_url = %config.relay_url,\n        health_port = config.health_port,\n        metrics_port = config.metrics_port,\n        max_frame_bytes = config.max_frame_bytes,\n        audit_enabled = config.audit_enabled,\n        \"Config loaded\"\n    );\n\n    let usage_interval_secs = usage_metrics_interval_secs();\n    let usage_idle_timeout_secs = usage_metrics_idle_timeout_secs(usage_interval_secs);\n    relay_metrics::install(config.metrics_port, usage_idle_timeout_secs);\n    metrics::gauge!(\"buzz_audit_enabled\").set(if config.audit_enabled { 1.0 } else { 0.0 });\n    info!(\n        port = config.metrics_port,\n        idle_timeout_secs = usage_idle_timeout_secs,","sourceCodeStart":126,"sourceCodeEnd":162,"githubUrl":"https://github.com/block/buzz/blob/f956e6fe06a76e50cbd8fba1a162482e752e7f1a/crates/buzz-relay/src/main.rs#L126-L162","documentation":"Fatal startup error wrapping any failure of Config::from_env(), which reads and validates the relay's environment variables. The underlying cause is logged as \"Invalid configuration: {e}\" just before this error is returned, and the process exits before binding any port. The wrapped message names the exact variable in practically all cases.","triggerScenarios":"Starting buzz-relay with a missing required variable (e.g. DATABASE_URL, REDIS_URL), a malformed URL, or a non-numeric value where a number is expected (pool sizes, ports, intervals).","commonSituations":"Forgot `cp .env.example .env` on a fresh clone; a Helm chart or CI secret missing a variable added in a newer release; typo'd variable names; values polluted with quotes or whitespace by secret managers.","solutions":["Read the \"Invalid configuration: {e}\" log line — it names the exact variable that failed","Diff your .env / deployment env against .env.example and add missing variables","Run a config lint in the deploy pipeline (source the env and assert required vars) before restarting","Check release notes after upgrading — new required config is the most common regression"],"exampleFix":"# before — relay exits: \"Configuration error: ...\"\nBUZZ_RELAY_URL=wss://relay.example.com\n# DATABASE_URL missing\n\n# after\nBUZZ_RELAY_URL=wss://relay.example.com\nDATABASE_URL=postgres://buzz:secret@db:5432/buzz\nREDIS_URL=redis://redis:6379","handlingStrategy":"validation","validationCode":"# Fail the deploy before the relay boots: every key in .env.example must be set.\nmissing=0\nwhile read -r key; do\n  [ -z \"${!key+x}\" ] && { echo \"missing env: $key\"; missing=1; }\ndone < <(grep -oE '^[A-Z_]+' .env.example)\nexit $missing","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat .env.example as the authoritative required-var list and diff it in CI","Source and validate env in the container entrypoint before exec'ing the relay","Watch release notes for newly required variables when upgrading"],"tags":["config","environment","env-vars","startup"],"backgroundTag":"invalid-environment-variable","analyzedSha":"f956e6fe06a76e50cbd8fba1a162482e752e7f1a","analyzedAt":"2026-08-16T22:11:40.750Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}