use_tls is false but broker_url uses 'mqtts://' (requires us

Error message

use_tls is false but broker_url uses 'mqtts://' (requires use_tls: true)

What it means

Mirror of the other TLS-agreement check: an `mqtts://` broker_url declares TLS, but `use_tls` defaults to `false` via serde, so adding an mqtts URL without explicitly setting the flag yields a contradictory config. The validator rejects it before connection so the listener never attempts a plain socket against a TLS port.

Source

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

        // 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() {
            anyhow::bail!("at least one topic must be configured");
        }

        // Client ID validation
        if self.client_id.is_empty() {
            validation_bail!(
                RequiredFieldEmpty,
                "client_id",
                "client_id must not be empty"
            );
        }

View on GitHub (pinned to 88bb9c8533)

Solutions

Add `use_tls = true` next to the mqtts URL.
Confirm port 8883 (or the broker's TLS port) is actually the TLS listener.
Keep scheme and flag edited together in one change.

Example fix

# before
broker_url = "mqtts://broker.example.com:8883"
# use_tls omitted (defaults to false)

# after
broker_url = "mqtts://broker.example.com:8883"
use_tls = true

Defensive patterns

Strategy: validation

Validate before calling

anyhow::ensure!(
    !(cfg.broker_url.starts_with("mqtts://") && !cfg.use_tls),
    "mqtts:// requires use_tls = true"
);

Type guard

fn tls_flag_matches(url: &str, use_tls: bool) -> bool {
    use_tls == url.starts_with("mqtts://")
}

Prevention

Never rely on defaults for use_tls — always write it explicitly next to broker_url.
The serde default is false; an mqtts URL alone will always fail until the flag is set.
Add a config-review checklist item: scheme and TLS flag must agree.

When it happens

Trigger: Adding `broker_url = "mqtts://broker.example.com:8883"` without a `use_tls` key (the flag silently defaults to false); temporarily commenting out `use_tls` while editing.

Common situations: The most common MQTT misconfiguration: operators add the TLS scheme and assume the flag follows it, but the flag has an independent serde default; also hit after migrating from plain to TLS brokers by editing only the URL.

Related errors

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