{"record":{"id":"38b9020b52cfea01","repo":"apache/seatunnel","slug":"mqtt-source-qos-must-be-0-or-1-got-qos","errorCode":null,"errorMessage":"MQTT source qos must be 0 or 1, got: ${qos}","messagePattern":"MQTT source qos must be 0 or 1, got: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-mqtt/src/main/java/org/apache/seatunnel/connectors/seatunnel/mqtt/source/MqttSourceConfig.java","lineNumber":71,"sourceCode":"        this.reconnectTimeout = config.get(MqttSourceOptions.RECONNECT_TIMEOUT);\n        this.maxQueueSize = config.get(MqttSourceOptions.MAX_QUEUE_SIZE);\n\n        String configuredClientId = config.get(MqttSourceOptions.CLIENT_ID);\n        if (!cleanSession && isBlank(configuredClientId)) {\n            throw new IllegalArgumentException(\n                    \"client_id is required when clean_session=false for MQTT source\");\n        }\n        this.clientId =\n                isBlank(configuredClientId)\n                        ? CLIENT_ID_PREFIX + UUID.randomUUID().toString()\n                        : configuredClientId;\n\n        validate();\n    }\n\n    private void validate() {\n        if (qos < 0 || qos > 1) {\n            throw new IllegalArgumentException(\"MQTT source qos must be 0 or 1, got: \" + qos);\n        }\n        if (!\"json\".equalsIgnoreCase(format) && !\"text\".equalsIgnoreCase(format)) {\n            throw new IllegalArgumentException(\"Unsupported MQTT source format: \" + format);\n        }\n        if (reconnectTimeout <= 0) {\n            throw new IllegalArgumentException(\n                    \"reconnect_timeout must be greater than 0, got: \" + reconnectTimeout);\n        }\n        if (maxQueueSize <= 0) {\n            throw new IllegalArgumentException(\n                    \"max_queue_size must be greater than 0, got: \" + maxQueueSize);\n        }\n    }\n\n    private static boolean isBlank(String value) {\n        return value == null || value.trim().isEmpty();\n    }\n","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-mqtt/src/main/java/org/apache/seatunnel/connectors/seatunnel/mqtt/source/MqttSourceConfig.java#L53-L89","documentation":"MqttSourceConfig.validate throws IllegalArgumentException when the configured qos is outside MQTT's supported subscription QoS range of 0..1 (this connector restricts to 0 or 1; QoS 2 is not supported). Validation runs at construction time, so the source fails fast at startup.","triggerScenarios":"Setting qos = 2 (or any negative/other value) in the MQTT source config; the value flows from the config option into validate() during source initialization.","commonSituations":"Assuming full MQTT QoS 2 support; copying broker-side QoS settings into the connector config; typos or unit confusion leading to out-of-range numbers.","solutions":["Set qos = 0 or qos = 1 in the source config","If exactly-once delivery is required, use qos = 1 combined with idempotent/idempotent-aware downstream processing rather than QoS 2","Check connector docs for the supported QoS range before configuring"],"exampleFix":"// before\nMqtt {\n  qos = 2\n}\n// after\nMqtt {\n  qos = 1\n}","handlingStrategy":"validation","validationCode":"if (qos < 0 || qos > 1) {\n  throw new IllegalArgumentException(\"MQTT source qos must be 0 or 1, got: \" + qos);\n}","typeGuard":"null","tryCatchPattern":"null","preventionTips":["Constrain qos config choices to 0 or 1 in tooling/templates","Do not assume QoS 2 support in this connector","Document the QoS restriction where configs are authored"],"tags":["mqtt","qos","validation","config"],"backgroundTag":"value-out-of-range","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}