invalid value for {capsule_id}.{key}: expected one of {}, go

Error message

invalid value for {capsule_id}.{key}: expected one of {}, got {resolved:?}

What it means

write_headless_env_fields resolves each env value (from --var or the environment variable) and, if the manifest declares enum_values for the field, enforces that the resolved value is one of them. A value outside the declared enum is rejected before it is written to the capsule.

Source

Thrown at crates/astrid-cli/src/commands/capsule/install_headless.rs:55

        let env_key = headless_env_key(&key);
        let supplied = vars
            .get(&key)
            .cloned()
            .or_else(|| std::env::var(&env_key).ok());
        if supplied.is_none() && existing_keys.contains(&key) {
            continue;
        }
        let resolved = supplied
            .or_else(|| def.default.as_ref().map(json_value_string))
            .ok_or_else(|| {
                anyhow::anyhow!(
                    "required value is missing for {capsule_id}.{key} \
                     (use --var {key}=… or set {env_key})"
                )
            })?;

        if !def.enum_values.is_empty() && !def.enum_values.iter().any(|item| item == &resolved) {
            anyhow::bail!(
                "invalid value for {capsule_id}.{key}: expected one of {}, got {resolved:?}",
                def.enum_values.join(", ")
            );
        }

        if def.env_type == "secret" {
            if resolved.is_empty() {
                delete_env_entry(principal, capsule_id, &key, EnvValueKind::Secret)?;
            } else {
                set_env_entry(
                    principal,
                    capsule_id,
                    &key,
                    &resolved,
                    EnvValueKind::Secret,
                    EnvStorageScope::Agent,
                )?;
            }

View on GitHub (pinned to affd8760f4)

Solutions

Set the value to one of the listed allowed values shown in the error message.
Check case-sensitivity and surrounding whitespace in the --var value or environment variable.
Read the capsule manifest's [env] section for the current set of enum_values (it may have changed across versions).
Unset any environment variable that may be supplying a stale value.

Example fix

// before
astrid capsule install github:org/repo --var log-level=verbose   # enum: debug, info, warn, error
// after
astrid capsule install github:org/repo --var log-level=info

Defensive patterns

Strategy: validation

Validate before calling

// check the value against the declared enum before install
let def = &manifest.env["log-level"];
if !def.enum_values.is_empty() && !def.enum_values.contains(&value) {
    panic!("{} not in {:?}", value, def.enum_values);
}

Prevention

Copy allowed values verbatim from the capsule docs/manifest, including case.
Trim whitespace and mind quoting in shell when passing --var values.
Unset environment variables that may inject stale values for the same field.

When it happens

Trigger: finish_install -> write_headless_env_fields resolves key K to a value (from --var K=… or env var) that is not present in def.enum_values for a field that declares an enum.

Common situations: Passing a value with wrong case or whitespace; supplying a deprecated enum option after a capsule upgrade; guessing a value like "yes" when the enum expects "true"; env variable holding a stale value overriding intent.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/cc1d8d12e4a3818e. Report an issue: GitHub.