apache/seatunnel · error · IllegalArgumentException

max_queue_size must be greater than 0, got: ${maxQueueSize}

Error message

max_queue_size must be greater than 0, got: ${maxQueueSize}

What it means

MqttSourceConfig.validate throws IllegalArgumentException when max_queue_size is zero or negative. This option bounds the internal buffer of messages between the MQTT client callback and the reader; it must be positive for the buffer to function. Failure occurs at source construction, before any network I/O.

Source

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

                        ? 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();
    }

    public String getUrl() {
        return url;
    }

    public String getTopic() {
        return topic;
    }

    public String getUsername() {
        return username;

View on GitHub (pinned to cf67b549a7)

Solutions

1. Set max_queue_size to a positive integer (e.g. 1000)
2. Tune based on expected throughput and backpressure tolerance rather than setting it to 0
3. Check docs for default value if unsure and remove the explicit option to use the default

Example fix

// before
Mqtt {
  max_queue_size = 0
}
// after
Mqtt {
  max_queue_size = 1000
}

if (maxQueueSize <= 0) {
  throw new IllegalArgumentException("max_queue_size must be > 0, got: " + maxQueueSize);
}

null

null

When it happens

Trigger: Setting max_queue_size = 0 or negative in the MQTT source config; placeholder values in templates; integer overflow attempts via very large negative inputs.

Common situations: Users trying to disable buffering by setting 0 (not supported); mis-scaled values when tuning memory; copied configs from connectors where 0 means unbounded.

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
• MQTT source qos must be 0 or 1, got: ${qos}
• Unsupported MQTT source format: ${format}
• reconnect_timeout must be greater than 0, got: ${reconnectTi
• ${optionPath} must be >= ${min} when set.

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