zeroclaw-labs/zeroclaw · error · anyhow::Error

auth_secret must contain only ASCII letters, numbers, unders

Error message

auth_secret must contain only ASCII letters, numbers, underscores, or hyphens

What it means

Thrown by HttpRequestTool::validate_secret_name (crates/zeroclaw-tools/src/http_request.rs:274) when the auth_secret name contains any character outside [A-Za-z0-9_-]. Names must be plain ASCII identifiers because they are used as TOML keys and to look up [http_request.secrets] entries. A common cause is passing the secret value, or an env-reference like "${MY_VAR}", in the auth_secret argument instead of a bare key name.

Source

Thrown at crates/zeroclaw-tools/src/http_request.rs:274

                })?;
                result.insert(header_name, header_value);
            }
        }
        Ok(result)
    }

    fn validate_secret_name(secret_name: &str) -> anyhow::Result<()> {
        if secret_name.is_empty() {
            anyhow::bail!("auth_secret cannot be empty");
        }
        if secret_name.len() > 64 {
            anyhow::bail!("auth_secret must be 64 characters or fewer");
        }
        if !secret_name
            .chars()
            .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
        {
            anyhow::bail!(
                "auth_secret must contain only ASCII letters, numbers, underscores, or hyphens"
            );
        }
        Ok(())
    }

    fn resolve_auth_secret(&self, secret_name: &str) -> anyhow::Result<String> {
        Self::validate_secret_name(secret_name)?;
        self.reload_auth_secret(secret_name)
    }

    fn reload_auth_secret(&self, secret_name: &str) -> anyhow::Result<String> {
        let config_path = self.config_path.as_ref().ok_or_else(|| {
            anyhow::Error::msg("auth_secret requires runtime config reload support")
        })?;
        if config_path.as_os_str().is_empty() {
            anyhow::bail!("auth_secret requires a config.toml path");
        }

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Pass only the bare key name defined under [http_request.secrets], using letters, digits, underscore, hyphen (e.g. "api_token").
2. To source the value from an environment variable, keep the name simple and set the config value to "${VAR_NAME}" instead.
3. Rename dotted/path-like keys in config.toml to underscore or hyphen forms.

Example fix

# before
[http_request.secrets]
"api.token" = "${MY_API_TOKEN}"
// caller: {"auth_secret": "${MY_API_TOKEN}"}

# after
[http_request.secrets]
api_token = "${MY_API_TOKEN}"
// caller: {"auth_secret": "api_token"}

fn secret_name_chars_ok(name: &str) -> bool {
    !name.is_empty()
        && name.len() <= 64
        && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
}

fn is_valid_secret_name(name: &str) -> bool {
    !name.is_empty()
        && name.len() <= 64
        && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
}

let result = tool.execute(args).await?;
if let Some(err) = &result.error {
    if err.contains("ASCII letters, numbers, underscores, or hyphens") {
        // caller sent a value or ${VAR} reference: use the bare config key name instead
    }
}

When it happens

Trigger: auth_secret = "my.secret" (dot), "api/token" (slash), "Bearer abc123" (the raw value), or "${MY_VAR}" (braces and $ are invalid; the ${...} form belongs in the config value, not the tool argument); names with spaces or non-ASCII characters.

Common situations: Confusing the secret's name with its value; pasting environment-reference syntax into the wrong place; kebab/dot naming habits from other config systems clashing with the allowed alphabet.

Related errors

• auth_secret cannot be empty
• auth_secret must be 64 characters or fewer
• environment-backed auth_secret '{inner}' must contain only A
• auth_secret requires a config.toml path
• auth_secret '{secret_name}' is empty after decryption

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/246c017d793cd2bd. Report an issue: GitHub.