{"record":{"id":"6f54c4bce790d6d9","repo":"pentaho/pentaho-kettle","slug":"mqttclientbuilder-error-qos","errorCode":"MQTTClientBuilder.Error.QOS","errorMessage":"MQTTClientBuilder.Error.QOS","messagePattern":"MQTTClientBuilder\\.Error\\.QOS","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"plugins/streaming/impls/mqtt/src/main/java/org/pentaho/di/trans/step/mqtt/MQTTClientBuilder.java","lineNumber":247,"sourceCode":"        initializedIntAray( Integer.parseInt( this.qos ) )\n      );\n    }\n    return client;\n  }\n\n  private String getProtocol() {\n    return isSecure ? SECURE_PROTOCOL : UNSECURE_PROTOCOL;\n  }\n\n  private void validateArgs() {\n    // expectation that the broker will contain the server:port.\n    checkArgument( this.broker.matches( \"^[^ :/]+:\\\\d+\" ),\n      getString( PKG, \"MQTTInput.Error.ConnectionURL\" ) );\n    try {\n      int qosVal = Integer.parseInt( this.qos );\n      checkArgument( qosVal >= 0 && qosVal <= 2 );\n    } catch ( Exception e ) {\n      throw new IllegalArgumentException( getString( PKG, \"MQTTClientBuilder.Error.QOS\", stepName, qos ) );\n    }\n  }\n\n  private int[] initializedIntAray( int val ) {\n    return IntStream.range( 0, topics.size() ).map( i -> val ).toArray();\n  }\n\n  private MqttConnectOptions getOptions() {\n    MqttConnectOptions options = new MqttConnectOptions();\n\n    if ( isSecure ) {\n      setSSLProps( options );\n    }\n    if ( !StringUtil.isEmpty( username ) ) {\n      options.setUserName( username );\n    }\n    if ( !StringUtil.isEmpty( password ) ) {\n      options.setPassword( password.toCharArray() );","sourceCodeStart":229,"sourceCodeEnd":265,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/streaming/impls/mqtt/src/main/java/org/pentaho/di/trans/step/mqtt/MQTTClientBuilder.java#L229-L265","documentation":"MQTTClientBuilder.validateArgs checks that the configured QoS value parses as an integer in [0,2]; on any failure it throws IllegalArgumentException with the localized 'Error.QOS' message, including the step name and the offending qos value. QoS here is stored as a string and must be 0 (at most once), 1 (at least once), or 2 (exactly once).","triggerScenarios":"buildAndConnect -> validateArgs when this.qos is null, empty, non-numeric (e.g. \"at-least-once\", \"2 \"), or an integer outside 0..2 (e.g. 3, -1).","commonSituations":"Users typing descriptive QoS names in the MQTT step dialog, variables whose default does not resolve to a number, or copying QoS values from MQTT 5 docs that allow other codes.","solutions":["Set the QoS field in the MQTT step to exactly 0, 1, or 2.","If using a variable/parameter for QoS, ensure it resolves to a plain integer string before the step runs.","Trim whitespace or quotes from the QOS value in your configuration/kettle.properties.","Add pre-save validation in the step dialog to reject non-0..2 input."],"exampleFix":"// before\nString qos = \"exactly-once\";   // invalid\nbuilder.setQos( qos );\n// after\nString qos = \"2\";              // must be 0, 1, or 2\nbuilder.setQos( qos );","handlingStrategy":"validation","validationCode":"public static boolean isValidQos( String qos ) {\n  try { int v = Integer.parseInt( qos == null ? \"\" : qos.trim() ); return v >= 0 && v <= 2; }\n  catch ( NumberFormatException e ) { return false; }\n}\n// call before buildAndConnect: if ( !isValidQos( qos ) ) throw new IllegalArgumentException( ... );","typeGuard":null,"tryCatchPattern":"try {\n  client = builder.buildAndConnect();\n} catch ( IllegalArgumentException e ) {\n  log.error( \"MQTT config invalid (check QoS is 0/1/2): \" + e.getMessage(), e );\n}","preventionTips":["Always configure QoS as the literal values 0, 1, or 2 — never names or variables without defaults.","Trim and normalize user-supplied QoS input in the step dialog before saving.","Set kettle.properties/parameter defaults for QoS variables so they always resolve to a number."],"tags":["mqtt","qos","validation","streaming"],"backgroundTag":"value-out-of-range","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}