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

iMessage channel is not configured

Error message

iMessage channel is not configured

What it means

Raised by build_channel_by_id in the feature-ENABLED iMessage arm: the channel is compiled in, but config.channels.imessage (a map of instances keyed by alias) contains no "default" key. Unlike the feature-gate bails, this is a pure configuration error — the code hardcodes alias "default" and requires [channels.imessage.default] to exist before constructing IMessageChannel. Any other alias key alone does not satisfy the check.

Source

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

                let alias = alias.clone();
                Arc::new(move || cfg_arc.read().channel_external_peers("mochat", &alias))
            };
            Ok(Arc::new(MochatChannel::new(
                mc.api_url.clone(),
                mc.api_token.clone(),
                alias,
                peer_resolver,
                mc.poll_interval_secs,
            )))
        }
        #[cfg(not(feature = "channel-mochat"))]
        "mochat" => {
            anyhow::bail!("Mochat channel requires the `channel-mochat` feature");
        }
        #[cfg(feature = "channel-imessage")]
        "imessage" => {
            if !config.channels.imessage.contains_key("default") {
                anyhow::bail!("iMessage channel is not configured");
            }
            let alias = "default".to_string();
            let peer_resolver: Arc<dyn Fn() -> Vec<String> + Send + Sync> = {
                let cfg_arc = config_arc.clone();
                let alias = alias.clone();
                Arc::new(move || cfg_arc.read().channel_external_peers("imessage", &alias))
            };
            Ok(Arc::new(IMessageChannel::new(alias, peer_resolver)))
        }
        #[cfg(not(feature = "channel-imessage"))]
        "imessage" => {
            anyhow::bail!("iMessage channel requires the `channel-imessage` feature");
        }
        "line" => {
            #[cfg(feature = "channel-line")]
            {
                let ln = config
                    .channels

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Add a [channels.imessage.default] section to the ZeroClaw config (the factory only reads the "default" key)
2. If you renamed the instance, either restore the key name to "default" or move the settings back under it
3. Reload/restart the daemon so the config is re-read, then confirm the error is gone
4. If the build lacks channel-imessage you will instead see error "iMessage channel requires the `channel-imessage` feature" — rebuild with that feature first

Example fix

# before
 # config.toml
 [channels.imessage]        # empty map -> contains_key("default") is false

 # after
 [channels.imessage.default]
 enabled = true

// gate on the exact condition the factory checks
let has_default = config
    .channels
    .imessage
    .as_ref()
    .map(|m| m.contains_key("default"))
    .unwrap_or(false);
if bindings.contains(&"imessage") && !has_default {
    eprintln!("add [channels.imessage.default] to the config before starting channels");
}

fn imessage_configured(cfg: &zeroclaw_config::schema::Config) -> bool {
    cfg.channels
        .imessage
        .as_ref()
        .map(|m| m.contains_key("default"))
        .unwrap_or(false)
}

match build_channel_by_id(&config_arc, "imessage") {
    Ok(ch) => { /* use */ }
    Err(e) if e.to_string() == "iMessage channel is not configured" => {
        // config fix, not a rebuild: create [channels.imessage.default] then reload
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: start_channels / build_channel_by_id with channel_id = "imessage", the channel-imessage feature compiled in, and [channels.imessage] absent, empty, or containing only non-"default" aliases (e.g. just [channels.imessage.phone]).

Common situations: Configuring iMessage for the first time and omitting the section; renaming the instance alias away from "default"; config generation tools that emit [channels.imessage] without a nested instance table; toggling imessage on in an agent binding without ever adding the channel block.

Related errors

• iMessage channel requires the `channel-imessage` feature
• model_provider `{ref_or_family}` does not resolve to a confi
• agents.{agent_alias}.model_provider is empty; runtime reload
• 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/b7f8145fc0b796cb. Report an issue: GitHub.