quickwit-oss/quickwit · error · anyhow::Error

failed to render config file template: environment variable

Error message

failed to render config file template: environment variable `{env_var_key}` is not set and no default value is provided

What it means

Quickwit node config files are templates: `{{ get_env(name="QW_LISTEN_ADDRESS", default="127.0.0.1") }}` placeholders are resolved by `render_config` before parsing. If a template references an environment variable that is not set and the call provides no `default=...`, rendering fails with this error and the config never loads.

Source

Thrown at quickwit/quickwit-config/src/templating.rs:74

                        .as_str()
                        .to_string()
                } else if let Ok(env_var_value) = std::env::var(env_var_key) {
                    debug!(
                        env_var_name=%env_var_key,
                        env_var_value=%env_var_value,
                        "environment variable is set, substituting with environment variable value"
                    );
                    env_var_value
                } else if let Some(default_match) = captures.get(2) {
                    let default_value = default_match.as_str().to_string();
                    debug!(
                        env_var_name=%env_var_key,
                        default_value=%default_value,
                        "environment variable is not set, substituting with default value"
                    );
                    default_value
                } else {
                    bail!(
                        "failed to render config file template: environment variable \
                         `{env_var_key}` is not set and no default value is provided"
                    );
                }
            };
            values.insert(env_var_key.to_string(), substitution_value);
        }
    }
    let template = Template::new(template_str).with_regex(&TEMPLATE_ENV_VAR_CAPTURE);
    let rendered = template
        .render_string(&values)
        .context("failed to render config file template")?;
    Ok(rendered)
}

#[cfg(test)]
mod test {
    use std::env;

View on GitHub (pinned to a39730c5cd)

Solutions

Set the referenced environment variable before starting Quickwit (e.g. `export QW_SEARCHER_ADDRESS=0.0.0.0`).
Add a `default="..."` argument to the `get_env` call in the config template.
Check the env var name for typos against what the deployment environment actually provides.

Example fix

// before (quickwit.yaml)
listen_address: "{{ get_env(name="QW_LISTEN_ADDRESS") }}"
// after
listen_address: "{{ get_env(name="QW_LISTEN_ADDRESS", default="127.0.0.1") }}"

Defensive patterns

Strategy: try-catch

Validate before calling

const required = [...config.matchAll(/get_env\(name="([^"]+)"(?![^)]*default)/g)].map(m => m[1]);
const missing = required.filter(v => process.env[v] === undefined);
if (missing.length) throw new Error(`unset config env vars: ${missing.join(",")}`);

Try / catch

match quickwit_config::load_node_config_from_file(&path) {
    Ok(cfg) => start_with(cfg),
    Err(e) if e.to_string().contains("is not set and no default value") => {
        eprintln!("missing env var for config template: {e}");
        std::process::exit(78); // config error
    }
    Err(e) => return Err(e),
}

Prevention

Always provide a `default="..."` in get_env calls for optional settings.
Declare required env vars in your deployment manifest (systemd EnvironmentFile, K8s env).
Smoke-test config rendering in CI with a minimal env.

When it happens

Trigger: Calling `render_config` (via `load_node_config_with_env`) on a config file containing `get_env(name="X")` where env var `X` is unset and no default value argument is supplied.

Common situations: Deploying Quickwit with a config that assumes env vars set by systemd/Docker/K8s that were never exported; typos in env var names; running the binary locally on a config written for a container environment.

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 quickwit-oss/quickwit@a39730c5cd (2026-09-08). Data as JSON: /api/errors/3ff84a9c4d554c7b. Report an issue: GitHub.