zeroclaw-labs/zeroclaw · error

broker_url must start with 'mqtt://' or 'mqtts://', got: {}

Error message

broker_url must start with 'mqtt://' or 'mqtts://', got: {}

What it means

`MqttConfig::validate` accepts only `mqtt://` (plain) and `mqtts://` (TLS) broker URLs, checked as a literal prefix of `broker_url`. Any other scheme — or no scheme at all — is rejected before connection because the listener cannot infer the transport.

Source

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

    ///
    /// Checks:
    /// - QoS is 0, 1, or 2
    /// - broker_url uses valid scheme (`mqtt://` or `mqtts://`)
    /// - `use_tls` flag matches broker_url scheme
    /// - At least one topic is configured
    /// - client_id is non-empty
    pub fn validate(&self) -> anyhow::Result<()> {
        // QoS validation
        if self.qos > 2 {
            anyhow::bail!("qos must be 0, 1, or 2, got {}", self.qos);
        }

        // Broker URL validation
        let is_tls_scheme = self.broker_url.starts_with("mqtts://");
        let is_mqtt_scheme = self.broker_url.starts_with("mqtt://");

        if !is_tls_scheme && !is_mqtt_scheme {
            anyhow::bail!(
                "broker_url must start with 'mqtt://' or 'mqtts://', got: {}",
                self.broker_url
            );
        }

        // TLS flag validation
        if is_mqtt_scheme && self.use_tls {
            anyhow::bail!("use_tls is true but broker_url uses 'mqtt://' (not 'mqtts://')");
        }

        if is_tls_scheme && !self.use_tls {
            anyhow::bail!(
                "use_tls is false but broker_url uses 'mqtts://' (requires use_tls: true)"
            );
        }

        // Topics validation
        if self.topics.is_empty() {

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Change the scheme to `mqtt://` for plain connections (e.g. `mqtt://localhost:1883`).
2. Use `mqtts://host:8883` for TLS and remember to set `use_tls = true` to match.
3. Double-check the pasted URL has no typos or missing slashes.

Example fix

# before
broker_url = "tcp://localhost:1883"

# after
broker_url = "mqtt://localhost:1883"

anyhow::ensure!(
    cfg.broker_url.starts_with("mqtt://") || cfg.broker_url.starts_with("mqtts://"),
    "bad broker_url scheme: {}",
    cfg.broker_url
);

fn is_mqtt_url(url: &str) -> bool {
    url.starts_with("mqtt://") || url.starts_with("mqtts://")
}

When it happens

Trigger: `broker_url = "tcp://localhost:1883"` (the scheme many mosquitto tools use), `broker_url = "localhost:1883"`, `http://`/`https://` prefixes, or a pasted URL with a typo like `mqtt:/`.

Common situations: Copying a `tcp://` URI from mosquitto/mqtt.js documentation; pasting a bare host:port from an infrastructure note; switching from another MQTT client library whose examples use different schemes.

Related errors

• amqp_url must start with 'amqp://' or 'amqps://', got: {}
• qos must be 0, 1, or 2, got {}
• use_tls is true but broker_url uses 'mqtt://' (not 'mqtts://
• use_tls is false but broker_url uses 'mqtts://' (requires us
• at least one topic must be configured

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