Hmbown/CodeWhale · error

agent profile {} {field} must be a simple token

Error message

agent profile {} {field} must be a simple token

What it means

validate_agent_profile_token requires id/name and base_role/role_hint to be simple tokens: non-empty, no leading/trailing whitespace, and only ASCII alphanumerics plus '-', '_' and '.' (is_agent_profile_token_char). Anything else - spaces, slashes, colons, unicode - is rejected because these values become roster keys and role identifiers.

Source

Thrown at crates/tui/src/fleet/profile.rs:469

            );
        }
        if permissions.approval_required == Some(false) {
            bail!(
                "agent profile {} may not disable approval_required",
                path.display()
            );
        }
    }
    Ok(())
}

fn validate_agent_profile_token(path: &Path, field: &str, value: &str) -> Result<()> {
    let trimmed = value.trim();
    if trimmed.is_empty() {
        bail!("agent profile {} {field} cannot be empty", path.display());
    }
    if trimmed != value || !trimmed.chars().all(is_agent_profile_token_char) {
        bail!(
            "agent profile {} {field} must be a simple token",
            path.display()
        );
    }
    Ok(())
}

fn validate_agent_profile_model_hint(path: &Path, value: Option<&str>) -> Result<()> {
    let Some(value) = value else {
        return Ok(());
    };
    if !is_model_hint(value) {
        bail!(
            "agent profile {} model must be a visible model id without whitespace or secrets",
            path.display()
        );
    }
    Ok(())

View on GitHub (pinned to 0c42157ee5)

Solutions

1. Change id/name/base_role to a slug: lowercase letters, digits, '-', '_', '.' only (e.g. "code-reviewer")
2. Move human-readable prose to display_name or description - those fields accept free text
3. Rename profile files whose stem contains spaces, since the stem becomes the id when id/name are absent

Example fix

# before
name = "code reviewer"

# after
id = "code-reviewer"
display_name = "Code Reviewer"

const fn is_agent_profile_token_char(c: char) -> bool {
    c.is_ascii_alphanumeric() || matches!(c, '-' | '_' | '.')
}

fn profile_fields_are_tokens(fields: &[&str]) -> bool {
    fields.iter().all(|v| {
        let t = v.trim();
        !t.is_empty() && t == *v && v.chars().all(is_agent_profile_token_char)
    })
}

fn is_profile_token(s: &str) -> bool {
    let t = s.trim();
    !t.is_empty() && t == s
        && t.chars().all(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '_' | '.'))
}

match load_agent_profile_file(&path) {
    Ok(p) => Ok(p),
    Err(err) if err.to_string().contains("must be a simple token") => {
        Err(anyhow!("profile {path:?}: use [A-Za-z0-9._-] slugs for id/name/base_role; put prose in display_name"))
    }
    Err(err) => Err(err),
}

When it happens

Trigger: id = "code reviewer" (inner space), base_role = "fleet/oracle", name = "codewhale agent" feeding the id, or a filename stem fallback like "my agent" from my agent.toml. The test suite reproduces it with id = "bad id".

Common situations: Putting a friendly multi-word label in name (which feeds the id) instead of display_name; role names copied with slashes or colons; profile files whose names contain spaces.

Related errors

• agent profile {} {field} cannot be empty
• agent profile {} provider cannot be empty
• agent profile {} provider must be a simple provider id
• agent profile {} may not disable approval_required
• agent profile {} model must be a visible model id without wh

AI-assisted analysis of Hmbown/CodeWhale@0c42157ee5 (2026-08-20). Data as JSON: /api/errors/0676ce2bf1967134. Report an issue: GitHub.