zeroclaw-labs/zeroclaw · critical

start_channels requires at least one enabled [agents.<alias>

Error message

start_channels requires at least one enabled [agents.<alias>] entry

What it means

Raised by start_channels (crates/zeroclaw-channels/src/orchestrator/mod.rs:11969), the channels supervisor entrypoint, when the resolved config contains zero `[agents.<alias>]` entries with enabled = true. The supervisor builds its enabled-agent roster before creating the observer and runtime adapter; an empty roster is fatal because there is nothing to attach channels to. Agent entries default to enabled = true, so this usually means agents were explicitly disabled or the [agents] tables are missing entirely.

Source

Thrown at crates/zeroclaw-channels/src/orchestrator/mod.rs:12006

            "Channels supervisor: no model configured. Waiting for reload \
             (complete onboarding at /onboard or set \
             [providers.models.<type>.<alias>] model = \"...\" and reload)."
        );
        cancel.cancelled().await;
        return Ok(());
    }

    zeroclaw_providers::pricing::spawn_refresher(config_arc.clone());

    let enabled_agents: Vec<String> = {
        let mut v: Vec<String> = config
            .agents
            .iter()
            .filter(|(_, a)| a.enabled)
            .map(|(alias, _)| alias.clone())
            .collect();
        if v.is_empty() {
            anyhow::bail!("start_channels requires at least one enabled [agents.<alias>] entry");
        }
        v.sort();
        v
    };

    let observer: Arc<dyn Observer> =
        Arc::from(observability::create_observer(&config.observability));
    let runtime: Arc<dyn platform::RuntimeAdapter> =
        Arc::from(platform::create_runtime(&config.runtime)?);

    // i18n is process-global; initialize once before the per-agent loop
    // touches tool descriptions.
    let i18n_locale = config
        .locale
        .as_deref()
        .filter(|s| !s.is_empty())
        .map(ToString::to_string)
        .unwrap_or_else(zeroclaw_runtime::i18n::detect_locale);

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Add or re-enable an agent: [agents.default] with enabled = true (the field defaults to true, so simply having the table without enabled = false is enough)
2. If the config was hand-trimmed, restore the [agents.<alias>] section from a backup or regenerate it via onboarding
3. Validate the config before launch by counting enabled agents (see validation below) so startup fails fast with a clearer message
4. If you intentionally want the daemon idle, note start_channels refuses to run with zero enabled agents — keep at least one enabled or do not start the channels supervisor

Example fix

# before
 # config.toml
 [agents.default]
 enabled = false        # sole agent disabled -> bail

 # after
 [agents.default]
 enabled = true

// fail fast with a clearer message than the supervisor's bail
let enabled: Vec<&str> = config
    .agents
    .iter()
    .filter(|(_, a)| a.enabled)
    .map(|(alias, _)| alias.as_str())
    .collect();
if enabled.is_empty() {
    anyhow::bail!(
        "config has no enabled [agents.<alias>] entries (found {} disabled): {}",
        config.agents.len(),
        config.agents.keys().cloned().collect::<Vec<_>>().join(", ")
    );
}

fn has_enabled_agent(cfg: &zeroclaw_config::schema::Config) -> bool {
    cfg.agents.values().any(|a| a.enabled)
}

if let Err(e) = start_channels(config, store, cancel, sop_engine, sop_audit).await {
    if e.to_string().contains("requires at least one enabled") {
        // fatal config error: prompt user to enable an [agents.<alias>] entry; do not retry
    }
    return Err(e);
}

When it happens

Trigger: Calling start_channels with a config where every [agents.<alias>] has enabled = false, or where no [agents.*] tables exist at all — e.g. a hand-edited config that disabled the default agent, a config generated by tooling that omits agents, or a fresh config that never completed onboarding.

Common situations: Operators setting enabled = false on all agents to 'park' the bot; config refactors that dropped the [agents.default] table; multi-agent configs where every alias was disabled for maintenance; automated deployments templating a config without the agents section. Related but distinct: if agents exist but none has a resolvable model provider, start_channels instead logs a WARN and waits for reload rather than bailing.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• agents.{agent_alias}.model_provider is empty; runtime reload
• git channel has no repositories to poll; set `repos` or gran
• model_provider `{ref_or_family}` does not resolve to a confi
• model_provider `{trimmed}` must use `<type>.<alias>` form
• model_provider `{trimmed}` does not resolve to a configured

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