What causes "Matrix channel requires the `channel-matrix` feature" in zeroclaw-labs/zeroclaw?

Rebuild with `cargo build --features channel-matrix`

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

Matrix channel requires the `channel-matrix` feature

Error message

Matrix channel requires the `channel-matrix` feature

What it means

Thrown by build_channel_by_id when channel_type is `matrix` and the crate was compiled without the `channel-matrix` cargo feature. Matrix uses a block-form match arm (feature on the inner block, bail in the cfg(not) block) rather than a separate arm, but the semantics match the other channel gates: the Matrix runtime code is not in the binary, so the channel cannot be built.

Source

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

                let alias = "default".to_string();
                let state_dir = matrix_state_dir(&config.config_path, &alias);
                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("matrix", &alias))
                };
                let ack = mx.ack_reactions.unwrap_or(config.channels.ack_reactions);
                let workspace_dir = one_shot_channel_workspace_dir(&config, "matrix", &alias);
                Ok(Arc::new(
                    MatrixChannel::new(mx.clone(), alias, peer_resolver, state_dir)?
                        .with_transcription(config.transcription.clone())
                        .with_workspace_dir(workspace_dir)
                        .with_ack_reactions(ack),
                ))
            }
            #[cfg(not(feature = "channel-matrix"))]
            {
                anyhow::bail!("Matrix channel requires the `channel-matrix` feature");
            }
        }
        "whatsapp" | "whatsapp-web" | "whatsapp_web" => {
            #[cfg(feature = "whatsapp-web")]
            {
                let wa = config
                    .channels
                    .whatsapp
                    .get("default")
                    .context("WhatsApp channel is not configured")?;
                if !wa.is_web_config() {
                    anyhow::bail!(
                        "WhatsApp channel send requires Web mode (set session_path, pair_phone, or mode = personal)"
                    );
                }
                let alias = "default".to_string();
                let peer_resolver: Arc<dyn Fn() -> Vec<String> + Send + Sync> = {
                    let cfg_arc = config_arc.clone();

View on GitHub (pinned to 88bb9c8533)

Solutions

Rebuild with `cargo build --features channel-matrix`
Choose a distribution build that enables matrix
Or strip `[channels.matrix]` from config so the channel is never instantiated

Example fix

# before
cargo build --no-default-features
# error: Matrix channel requires the `channel-matrix` feature

# after
cargo build --no-default-features --features channel-matrix

Defensive patterns

Strategy: validation

Validate before calling

#[cfg(not(feature = "channel-matrix"))]
if !config.channels.matrix.is_empty() {
    log::warn!("[channels.matrix.*] configured but `channel-matrix` feature is off");
}

Type guard

fn channel_feature_enabled(channel_type: &str) -> bool {
    match channel_type {
        "matrix" => cfg!(feature = "channel-matrix"),
        "telegram" => cfg!(feature = "channel-telegram"),
        "discord" => cfg!(feature = "channel-discord"),
        "slack" => cfg!(feature = "channel-slack"),
        "mattermost" => cfg!(feature = "channel-mattermost"),
        "signal" => cfg!(feature = "channel-signal"),
        "whatsapp" | "whatsapp-web" => cfg!(feature = "whatsapp-web"),
        _ => false,
    }
}

Try / catch

Err(err) if err.to_string().contains("requires the `channel-matrix` feature") => {
    // rebuild with --features channel-matrix or remove matrix sections
}

Prevention

Add a startup assertion that every configured channel type has its feature compiled
Keep a build matrix in CI covering the feature combinations you actually ship
Document the full channel->feature mapping in one table

When it happens

Trigger: A `[channels.matrix.*]` section or `matrix.<alias>` send target on a binary lacking `channel-matrix`; hit at daemon channel construction and in the one-shot delivery path.

Common situations: Minimal builds; feature sets changed across versions; config migrated from a matrix-enabled deployment to one that is not.

Related errors

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