zeroclaw-labs/zeroclaw · error

at least one routing key must be configured

Error message

at least one routing key must be configured

What it means

The AMQP consumer binds a queue to an exchange using one or more routing keys; `routing_keys` has a serde default of an empty vec, and validation requires at least one entry because a binding with no keys receives no deliveries. The exchange name itself is checked separately (non-empty) before this.

Source

Thrown at crates/zeroclaw-config/src/schema.rs:16636

            (true, false) => {
                anyhow::bail!(
                    "client_cert is set but client_key is missing (both are required for mutual TLS)"
                )
            }
            (false, true) => {
                anyhow::bail!(
                    "client_key is set but client_cert is missing (both are required for mutual TLS)"
                )
            }
            _ => {}
        }

        if self.exchange.is_empty() {
            validation_bail!(RequiredFieldEmpty, "exchange", "exchange must not be empty");
        }

        if self.routing_keys.is_empty() {
            anyhow::bail!("at least one routing key must be configured");
        }

        Ok(())
    }
}

impl ChannelConfig for AmqpConfig {
    fn name() -> &'static str {
        "AMQP"
    }
    fn desc() -> &'static str {
        "AMQP topic consumer"
    }
}

fn default_amqp_sender_label() -> String {
    "amqp".to_string()
}

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Add at least one binding key, e.g. `routing_keys = ["zeroclaw.events.#"]` or the Fedora Messaging convention `org.fedoraproject.#`.
2. Use `#` explicitly if you intend to receive everything from the exchange.
3. Confirm the keys match what publishers set, otherwise the channel starts but stays silent.

Example fix

# before
exchange = "events"
routing_keys = []

# after
exchange = "events"
routing_keys = ["zeroclaw.events.#"]

anyhow::ensure!(
    !cfg.routing_keys.is_empty(),
    "amqp channel needs at least one routing key binding"
);

When it happens

Trigger: A `[channels.amqp.<alias>]` block with `exchange` set but `routing_keys` omitted or set to `[]`; trimming keys while debugging bindings and reloading; migrating from queue-name-based consumers where routing keys do not exist.

Common situations: Configuring a Fedora Messaging or RabbitMQ topic exchange for the first time; expecting `#` (match-all) to be implicit — it is not, you must write `routing_keys = ["#"]`; templated configs where the keys array renders empty.

Related errors

• amqp_url must start with 'amqp://' or 'amqps://', got: {}
• at least one topic must be configured
• at least one path must be configured
• amqps:// requires ca_cert to verify the broker
• client_cert is set but client_key is missing (both are requi

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