{"record":{"id":"4bf4cb9136adf6cf","repo":"zeroclaw-labs/zeroclaw","slug":"use-tls-is-true-but-broker-url-uses-mqtt-not","errorCode":null,"errorMessage":"use_tls is true but broker_url uses 'mqtt://' (not 'mqtts://')","messagePattern":"use_tls is true but broker_url uses 'mqtt://' \\(not 'mqtts://'\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/zeroclaw-config/src/schema.rs","lineNumber":16271,"sourceCode":"        // QoS validation\n        if self.qos > 2 {\n            anyhow::bail!(\"qos must be 0, 1, or 2, got {}\", self.qos);\n        }\n\n        // Broker URL validation\n        let is_tls_scheme = self.broker_url.starts_with(\"mqtts://\");\n        let is_mqtt_scheme = self.broker_url.starts_with(\"mqtt://\");\n\n        if !is_tls_scheme && !is_mqtt_scheme {\n            anyhow::bail!(\n                \"broker_url must start with 'mqtt://' or 'mqtts://', got: {}\",\n                self.broker_url\n            );\n        }\n\n        // TLS flag validation\n        if is_mqtt_scheme && self.use_tls {\n            anyhow::bail!(\"use_tls is true but broker_url uses 'mqtt://' (not 'mqtts://')\");\n        }\n\n        if is_tls_scheme && !self.use_tls {\n            anyhow::bail!(\n                \"use_tls is false but broker_url uses 'mqtts://' (requires use_tls: true)\"\n            );\n        }\n\n        // Topics validation\n        if self.topics.is_empty() {\n            anyhow::bail!(\"at least one topic must be configured\");\n        }\n\n        // Client ID validation\n        if self.client_id.is_empty() {\n            validation_bail!(\n                RequiredFieldEmpty,\n                \"client_id\",","sourceCodeStart":16253,"sourceCodeEnd":16289,"githubUrl":"https://github.com/zeroclaw-labs/zeroclaw/blob/88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc/crates/zeroclaw-config/src/schema.rs#L16253-L16289","documentation":"The MQTT channel encodes transport security twice: in the `broker_url` scheme and in the `use_tls` flag. The validator requires them to agree; `use_tls = true` together with an `mqtt://` URL states 'encrypt this plain connection', which the runtime cannot honor, so the config is rejected before connect.","triggerScenarios":"`broker_url = \"mqtt://broker.example.com:1883\"` with `use_tls = true`; flipping `use_tls` on while troubleshooting connectivity but keeping the plain URL.","commonSituations":"Enabling TLS by toggling only the flag after reading generic MQTT advice; copying a `use_tls = true` snippet onto an existing plain-transport config; brokers that accept TLS on the plain port (TLS via port 1883) — this config shape does not support that.","solutions":["If the broker port is plain (1883), set `use_tls = false`.","If you want TLS, switch the URL to `mqtts://broker.example.com:8883` and keep `use_tls = true`.","Verify the broker's TLS listener port before choosing."],"exampleFix":"# before\nbroker_url = \"mqtt://broker.example.com:1883\"\nuse_tls = true\n\n# after\nbroker_url = \"mqtts://broker.example.com:8883\"\nuse_tls = true","handlingStrategy":"validation","validationCode":"let tls_scheme = cfg.broker_url.starts_with(\"mqtts://\");\nanyhow::ensure!(\n    cfg.use_tls == tls_scheme,\n    \"use_tls must match the broker_url scheme\"\n);","typeGuard":"fn tls_flag_matches(url: &str, use_tls: bool) -> bool {\n    use_tls == url.starts_with(\"mqtts://\")\n}","tryCatchPattern":null,"preventionTips":["Treat scheme and use_tls as one unit: edit them together.","Prefer deriving use_tls from the scheme in whatever generates your config.","When enabling TLS, also verify the port is the TLS listener."],"tags":["mqtt","config","tls","zeroclaw"],"backgroundTag":"tls-config-mismatch","analyzedSha":"88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc","analyzedAt":"2026-08-23T01:07:41.857Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}