{"record":{"id":"aa222afdb27f12fd","repo":"zeroclaw-labs/zeroclaw","slug":"use-tls-is-false-but-broker-url-uses-mqtts-r","errorCode":null,"errorMessage":"use_tls is false but broker_url uses 'mqtts://' (requires use_tls: true)","messagePattern":"use_tls is false but broker_url uses 'mqtts://' \\(requires use_tls: true\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/zeroclaw-config/src/schema.rs","lineNumber":16275,"sourceCode":"\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\",\n                \"client_id must not be empty\"\n            );\n        }\n","sourceCodeStart":16257,"sourceCodeEnd":16293,"githubUrl":"https://github.com/zeroclaw-labs/zeroclaw/blob/88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc/crates/zeroclaw-config/src/schema.rs#L16257-L16293","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nbroker_url = \"mqtts://broker.example.com:8883\"\n# use_tls omitted (defaults to false)\n\n# after\nbroker_url = \"mqtts://broker.example.com:8883\"\nuse_tls = true","handlingStrategy":"validation","validationCode":"anyhow::ensure!(\n    !(cfg.broker_url.starts_with(\"mqtts://\") && !cfg.use_tls),\n    \"mqtts:// requires use_tls = true\"\n);","typeGuard":"fn tls_flag_matches(url: &str, use_tls: bool) -> bool {\n    use_tls == url.starts_with(\"mqtts://\")\n}","tryCatchPattern":null,"preventionTips":["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."],"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"}