{"record":{"id":"d81b4c7caa416fbd","repo":"apache/seatunnel","slug":"client-id-is-required-when-clean-session-false-for","errorCode":null,"errorMessage":"client_id is required when clean_session=false for MQTT source","messagePattern":"client_id is required when clean_session=false for MQTT source","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":58,"sourceCode":"    private final int maxQueueSize;\n\n    public MqttSourceConfig(ReadonlyConfig config) {\n        this.url = config.get(MqttSourceOptions.URL);\n        this.topic = config.get(MqttSourceOptions.TOPIC);\n        this.username = config.get(MqttSourceOptions.USERNAME);\n        this.password = config.get(MqttSourceOptions.PASSWORD);\n        this.qos = config.get(MqttSourceOptions.QOS);\n        this.format = config.get(MqttSourceOptions.FORMAT);\n        this.fieldDelimiter = config.get(MqttSourceOptions.FIELD_DELIMITER);\n        this.cleanSession = config.get(MqttSourceOptions.CLEAN_SESSION);\n        this.connectionTimeout = config.get(MqttSourceOptions.CONNECTION_TIMEOUT);\n        this.keepAliveInterval = config.get(MqttSourceOptions.KEEP_ALIVE_INTERVAL);\n        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) {","sourceCodeStart":40,"sourceCodeEnd":76,"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#L40-L76","documentation":"MqttSourceConfig's constructor throws IllegalArgumentException when clean_session=false but no client_id is configured. With a persistent session, the broker stores subscriptions against the client_id, so an auto-generated random client_id would create a new orphaned session on every reconnect. A client_id is mandatory to make clean_session=false meaningful.","triggerScenarios":"Configuring the MQTT source with clean_session = false while omitting client_id (or providing only whitespace, which isBlank also rejects); constructor fails during source initialization.","commonSituations":"Users enabling persistent sessions for at-least-once semantics but forgetting client_id; copying example configs that use auto-generated client ids; whitespace-only client_id values that look set but are blank.","solutions":["Add an explicit, stable client_id to the MQTT source config","Alternatively set clean_session = true if persistence is not required","Ensure the client_id is unique per source instance sharing the same broker"],"exampleFix":"// before\nsource {\n  Mqtt {\n    clean_session = false\n  }\n}\n// after\nsource {\n  Mqtt {\n    clean_session = false\n    client_id = \"seatunnel-source-1\"\n  }\n}","handlingStrategy":"validation","validationCode":"if (!cleanSession && (clientId == null || clientId.trim().isEmpty())) {\n  throw new IllegalArgumentException(\"client_id is required when clean_session=false\");\n}","typeGuard":"null","tryCatchPattern":"null","preventionTips":["Pair clean_session=false with an explicit stable client_id by convention","Reject blank/whitespace client_id values in config review","Keep client_id unique per parallel source instance"],"tags":["mqtt","config","client-id","validation"],"backgroundTag":"missing-required-config-field","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"}