{"record":{"id":"ab7941be163050b9","repo":"quickwit-oss/quickwit","slug":"qw-metrics-labels-env-var-must-contain-valid-uni","errorCode":null,"errorMessage":"{QW_METRICS_LABELS_ENV_VAR} must contain valid Unicode","messagePattern":"(.+?) must contain valid Unicode","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"quickwit/quickwit-metrics/src/lib.rs","lineNumber":407,"sourceCode":"        (c.info.key_name, buckets)\n    })\n}\n\n/// Initializes the global metrics labels from the environment variable.\npub fn init_metrics_labels_env_var() -> anyhow::Result<()> {\n    // If the labels environment variable is already initialized, return early.\n    if LABELS_ENV_VAR.get().is_some() {\n        return Ok(());\n    }\n\n    // quickwit-common defines common helpers for getting environment variables.\n    // However, we need to use the `std::env::var` function directly here because\n    // quickwit-common depends on quickwit-metrics and it would cause a circular dependency.\n    let labels = match std::env::var(QW_METRICS_LABELS_ENV_VAR) {\n        Ok(labels) => labels,\n        Err(std::env::VarError::NotPresent) => String::new(),\n        Err(std::env::VarError::NotUnicode(_)) => {\n            anyhow::bail!(\"{QW_METRICS_LABELS_ENV_VAR} must contain valid Unicode\")\n        }\n    };\n    let parsed_labels = parse_metrics_labels(&labels)?;\n    LABELS_ENV_VAR.get_or_init(|| parsed_labels.into_boxed_slice());\n\n    Ok(())\n}\n\n// The format of the environment variable is:\n// QW_METRICS_LABELS=\"environment=test,region=us-east-1,foo=bar\"\nfn parse_metrics_labels(labels: &str) -> anyhow::Result<Vec<Label>> {\n    let mut parsed_labels: Vec<Label> = Vec::new();\n    if labels.trim().is_empty() {\n        return Ok(parsed_labels);\n    }\n\n    const LABELS_SEPARATOR: char = ',';\n    const KEY_VALUE_SEPARATOR: char = '=';","sourceCodeStart":389,"sourceCodeEnd":425,"githubUrl":"https://github.com/quickwit-oss/quickwit/blob/a39730c5cdcd1a4fe798403737ae293999ea21f8/quickwit/quickwit-metrics/src/lib.rs#L389-L425","documentation":"init_metrics_labels_env_var reads QW_METRICS_LABELS_ENV_VAR directly from the environment (to avoid a circular dependency on quickwit-common) and bails if its value is not valid Unicode. Quickwit cannot attach the configured metric labels without a decodable value.","triggerScenarios":"Starting Quickwit with QW_METRICS_LABELS_ENV_VAR set to bytes that are not valid UTF-8 (e.g. raw binary or a non-UTF-8 locale-encoded value in the environment).","commonSituations":"Exporting the env var from a script with mis-encoded bytes; setting it via a container runtime that injects raw values; shell locale issues.","solutions":["Re-set the variable with valid UTF-8, e.g. export QW_METRICS_LABELS_ENV_VAR=\"cluster=prod\"","Check the source of the value with `env | grep QW_METRICS` and re-encode it (e.g. iconv)","Remove the variable entirely to fall back to the empty default"],"exampleFix":"// before\nexport QW_METRICS_LABELS_ENV_VAR=$'cluster=pr\\xffod'\n// after\nexport QW_METRICS_LABELS_ENV_VAR=\"cluster=prod\"","handlingStrategy":"validation","validationCode":"if let Ok(v) = std::env::var(\"QW_METRICS_LABELS_ENV_VAR\") {\n    if std::str::from_utf8(v.as_bytes()).is_err() { eprintln!(\"value is not valid UTF-8\"); }\n}","typeGuard":null,"tryCatchPattern":"if let Err(e) = init_metrics_labels_env_var() {\n    if e.to_string().contains(\"valid Unicode\") {\n        eprintln!(\"fix QW_METRICS_LABELS_ENV_VAR encoding: {e}\");\n        std::process::exit(1);\n    }\n}","preventionTips":["Set the env var only from UTF-8-safe sources","Avoid passing binary/raw values through container runtime env injection","Test startup scripts under the target locale/encoding"],"tags":["metrics","env-var","encoding","config"],"backgroundTag":"invalid-env-var-value","analyzedSha":"a39730c5cdcd1a4fe798403737ae293999ea21f8","analyzedAt":"2026-09-08T13:19:37.784Z","contentChangedAt":"2026-09-08T13:19:37.784Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}