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

Unknown agent {agent_alias:?} (no [agents.{agent_alias}] ent

Error message

Unknown agent {agent_alias:?} (no [agents.{agent_alias}] entry configured)

What it means

Every cron subcommand resolves its agent through require_configured_agent, which requires an [agents.<alias>] table in the loaded zeroclaw config. When the alias has no such entry, the command is rejected (a Reject WARN event is logged with the alias) before anything is scheduled.

Source

Thrown at src/cron/mod.rs:17

pub use zeroclaw_runtime::cron::*;

use crate::config::Config;
use anyhow::{Result, bail};
use zeroclaw_runtime::i18n::{get_required_cli_string, get_required_cli_string_with_args};

/// Bail with a clear error if the named agent isn't configured.
fn require_configured_agent(config: &Config, agent_alias: &str) -> Result<()> {
    if config.agent(agent_alias).is_none() {
        ::zeroclaw_log::record!(
            WARN,
            ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Reject)
                .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                .with_attrs(::serde_json::json!({"agent_alias": agent_alias})),
            "cron CLI rejected: unknown agent alias"
        );
        anyhow::bail!("Unknown agent {agent_alias:?} (no [agents.{agent_alias}] entry configured)");
    }
    Ok(())
}

fn parse_explicit_rfc3339_utc(raw: &str) -> Result<chrono::DateTime<chrono::Utc>> {
    chrono::DateTime::parse_from_rfc3339(raw)
        .map(|timestamp| timestamp.with_timezone(&chrono::Utc))
        .map_err(|err| {
            ::zeroclaw_log::record!(
                WARN,
                ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Reject)
                    .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                    .with_attrs(::serde_json::json!({
                        "raw": raw,
                        "error": format!("{}", err),
                    })),
                "cron --at rejected: timestamp lacks explicit Z/offset or is malformed"
            );

View on GitHub (pinned to 88bb9c8533)

Solutions

Open the active config file and check the exact spelling of the [agents.<alias>] tables; fix the command to use one of them.
If the agent is new, add its [agents.<alias>] section to the config first, then re-run the cron command.
Verify which config file zeroclaw actually loaded (env overrides, --config flag) if the table exists somewhere else.
Standardize scripts on the canonical alias instead of hardcoded names across environments.

Example fix

# before: cron add references an unconfigured alias
zeroclaw cron add my-bot --prompt 'daily report'
# after: add the agent table first
# zeroclaw.toml:
# [agents.my-bot]
# provider = "openai"
zeroclaw cron add my-bot --prompt 'daily report'

Defensive patterns

Strategy: validation

Validate before calling

use serde::Deserialize;
#[derive(Deserialize)]
struct Config { agents: std::collections::BTreeMap<String, serde_json::Value> }
fn agent_exists(cfg_text: &str, alias: &str) -> bool {
    toml::from_str::<Config>(cfg_text)
        .map(|c| c.agents.contains_key(alias))
        .unwrap_or(false)
}
// validate alias against the same config zeroclaw loads before running cron cmds

Try / catch

match handle_cron(cmd).await {
    Err(e) if e.to_string().starts_with("Unknown agent") => {
        // bad alias: check [agents.*] tables in the active config, fix and retry
    }
    other => other,
}

Prevention

Define all agent aliases in one reviewed config change before scheduling jobs against them.
Validate alias arguments against the config in wrapper scripts before invoking cron subcommands.
Pin the config path explicitly (--config / env) in automation so aliases resolve against the expected file.

When it happens

Trigger: Any `zeroclaw cron add|add-at|add-every|once|update <agent_alias> ...` invocation where the config file has no [agents.<agent_alias>] table: typo in the alias, alias renamed in config, or the wrong config file is being loaded.

Common situations: Fresh install with no agents configured yet; scripts written against an old alias after config reorganization; ZEROCLAW_CONFIG or --config pointing at a different file than expected; case mismatch in the alias.

Related errors

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