apache/seatunnel · error · IllegalArgumentException

MQTT source qos must be 0 or 1, got: ${qos}

Error message

MQTT source qos must be 0 or 1, got: ${qos}

What it means

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.

Source

Thrown at seatunnel-connectors-v2/connector-mqtt/src/main/java/org/apache/seatunnel/connectors/seatunnel/mqtt/source/MqttSourceConfig.java:71

        this.reconnectTimeout = config.get(MqttSourceOptions.RECONNECT_TIMEOUT);
        this.maxQueueSize = config.get(MqttSourceOptions.MAX_QUEUE_SIZE);

        String configuredClientId = config.get(MqttSourceOptions.CLIENT_ID);
        if (!cleanSession && isBlank(configuredClientId)) {
            throw new IllegalArgumentException(
                    "client_id is required when clean_session=false for MQTT source");
        }
        this.clientId =
                isBlank(configuredClientId)
                        ? CLIENT_ID_PREFIX + UUID.randomUUID().toString()
                        : configuredClientId;

        validate();
    }

    private void validate() {
        if (qos < 0 || qos > 1) {
            throw new IllegalArgumentException("MQTT source qos must be 0 or 1, got: " + qos);
        }
        if (!"json".equalsIgnoreCase(format) && !"text".equalsIgnoreCase(format)) {
            throw new IllegalArgumentException("Unsupported MQTT source format: " + format);
        }
        if (reconnectTimeout <= 0) {
            throw new IllegalArgumentException(
                    "reconnect_timeout must be greater than 0, got: " + reconnectTimeout);
        }
        if (maxQueueSize <= 0) {
            throw new IllegalArgumentException(
                    "max_queue_size must be greater than 0, got: " + maxQueueSize);
        }
    }

    private static boolean isBlank(String value) {
        return value == null || value.trim().isEmpty();
    }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Set qos = 0 or qos = 1 in the source config
2. If exactly-once delivery is required, use qos = 1 combined with idempotent/idempotent-aware downstream processing rather than QoS 2
3. Check connector docs for the supported QoS range before configuring

Example fix

// before
Mqtt {
  qos = 2
}
// after
Mqtt {
  qos = 1
}

if (qos < 0 || qos > 1) {
  throw new IllegalArgumentException("MQTT source qos must be 0 or 1, got: " + qos);
}

null

null

When it happens

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

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

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

• client_id is required when clean_session=false for MQTT sour
• Unsupported MQTT source format: ${format}
• reconnect_timeout must be greater than 0, got: ${reconnectTi
• max_queue_size must be greater than 0, got: ${maxQueueSize}
• Schema config can not be empty

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/38b9020b52cfea01. Report an issue: GitHub.