pentaho/pentaho-kettle · error · IllegalArgumentException

MQTTClientBuilder.Error.QOS

MQTTClientBuilder.Error.QOS

Error message

MQTTClientBuilder.Error.QOS

What it means

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).

Solutions

1. Set the QoS field in the MQTT step to exactly 0, 1, or 2.
2. If using a variable/parameter for QoS, ensure it resolves to a plain integer string before the step runs.
3. Trim whitespace or quotes from the QOS value in your configuration/kettle.properties.
4. Add pre-save validation in the step dialog to reject non-0..2 input.

Example fix

// before
String qos = "exactly-once";   // invalid
builder.setQos( qos );
// after
String qos = "2";              // must be 0, 1, or 2
builder.setQos( qos );

public static boolean isValidQos( String qos ) {
  try { int v = Integer.parseInt( qos == null ? "" : qos.trim() ); return v >= 0 && v <= 2; }
  catch ( NumberFormatException e ) { return false; }
}
// call before buildAndConnect: if ( !isValidQos( qos ) ) throw new IllegalArgumentException( ... );

try {
  client = builder.buildAndConnect();
} catch ( IllegalArgumentException e ) {
  log.error( "MQTT config invalid (check QoS is 0/1/2): " + e.getMessage(), e );
}

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• A connection of type PALO is expected
• A connection of type PALO is expected
• A server socket allocation always has to accompanied by a…
• A server socket allocation always has to accompanied by…
• Append.Exception.InvalidLayoutDetected

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/6f54c4bce790d6d9. Report an issue: GitHub.

Appendix: source

Thrown at plugins/streaming/impls/mqtt/src/main/java/org/pentaho/di/trans/step/mqtt/MQTTClientBuilder.java:247

        initializedIntAray( Integer.parseInt( this.qos ) )
      );
    }
    return client;
  }

  private String getProtocol() {
    return isSecure ? SECURE_PROTOCOL : UNSECURE_PROTOCOL;
  }

  private void validateArgs() {
    // expectation that the broker will contain the server:port.
    checkArgument( this.broker.matches( "^[^ :/]+:\\d+" ),
      getString( PKG, "MQTTInput.Error.ConnectionURL" ) );
    try {
      int qosVal = Integer.parseInt( this.qos );
      checkArgument( qosVal >= 0 && qosVal <= 2 );
    } catch ( Exception e ) {
      throw new IllegalArgumentException( getString( PKG, "MQTTClientBuilder.Error.QOS", stepName, qos ) );
    }
  }

  private int[] initializedIntAray( int val ) {
    return IntStream.range( 0, topics.size() ).map( i -> val ).toArray();
  }

  private MqttConnectOptions getOptions() {
    MqttConnectOptions options = new MqttConnectOptions();

    if ( isSecure ) {
      setSSLProps( options );
    }
    if ( !StringUtil.isEmpty( username ) ) {
      options.setUserName( username );
    }
    if ( !StringUtil.isEmpty( password ) ) {
      options.setPassword( password.toCharArray() );

View on GitHub (pinned to f3058517a1)