apache/seatunnel · error · IllegalArgumentException

Option 'queue_name' must contain 3-63 lowercase letters, num

Error message

Option 'queue_name' must contain 3-63 lowercase letters, numbers or single hyphens

What it means

AzureQueueConfigValidator.validateClient rejects queue names that violate Azure Storage queue naming rules: length must be 3–63 characters, only lowercase letters, digits, and single (non-repeated) hyphens, matching QUEUE_NAME_PATTERN. Thrown as IllegalArgumentException before any client is created.

Source

Thrown at seatunnel-connectors-v2/connector-azure-queue-storage/src/main/java/org/apache/seatunnel/connectors/seatunnel/azure/queue/config/AzureQueueConfigValidator.java:35

package org.apache.seatunnel.connectors.seatunnel.azure.queue.config;

import java.util.regex.Pattern;

final class AzureQueueConfigValidator {

    private static final Pattern QUEUE_NAME_PATTERN =
            Pattern.compile("[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])?");

    private AzureQueueConfigValidator() {}

    static void validateClient(AzureQueueClientConfig config) {
        requireNonBlank(config.getQueueName(), "queue_name");
        if (config.getQueueName().length() < 3
                || config.getQueueName().length() > 63
                || !QUEUE_NAME_PATTERN.matcher(config.getQueueName()).matches()
                || config.getQueueName().contains("--")) {
            throw new IllegalArgumentException(
                    "Option 'queue_name' must contain 3-63 lowercase letters, numbers or single hyphens");
        }
        if (config.getAuthenticationType() == null) {
            throw new IllegalArgumentException("Option 'authentication_type' is required");
        }

        switch (config.getAuthenticationType()) {
            case CONNECTION_STRING:
                requireNonBlank(config.getConnectionString(), "connection_string");
                rejectPresent(
                        config.getEndpoint(),
                        "endpoint",
                        config.getAccountName(),
                        "account_name",
                        config.getAccountKey(),
                        "account_key",
                        config.getSasToken(),
                        "sas_token");

View on GitHub (pinned to cf67b549a7)

Solutions

Rename the queue to 3-63 lowercase letters, digits, and single hyphens (no '--', no leading/trailing hyphen)
Create the queue in Azure with a compliant name if it doesn't exist
Validate locally: java.util.regex match [a-z0-9](-[a-z0-9])* and length 3-63

Example fix

// before
queue_name = "My_Queue--prod"
// after
queue_name = "my-queue-prod"

Defensive patterns

Strategy: validation

Validate before calling

java.util.regex.Pattern p = java.util.regex.Pattern.compile("^[a-z0-9]([a-z0-9]-[a-z0-9])*$");
String q = config.getQueueName();
boolean ok = q != null && q.length() >= 3 && q.length() <= 63 && p.matcher(q).matches() && !q.contains("--");
if (!ok) throw new IllegalArgumentException("Invalid Azure queue name: " + q);

Try / catch

try { validate(config); } catch (IllegalArgumentException e) { if (e.getMessage().contains("queue_name")) { log.error("Rename queue to 3-63 lowercase chars/digits/single hyphens"); } throw e; }

Prevention

Follow Azure queue naming: 3-63 chars, lowercase alphanumeric, single hyphens only, no leading/trailing hyphen
Never reuse account names or connection strings as queue names
Generate queue names programmatically with a slugify + length check
Add queue-name validation to your deployment config linter

When it happens

Trigger: validateClient called with queue_name shorter than 3 or longer than 63 chars, containing uppercase/invalid characters, or containing consecutive hyphens ('--').

Common situations: Uppercase or underscore in queue name (Azure forbids both); trailing/leading hyphen; accidentally using the storage account name or connection string as queue_name; double hyphen from templated names.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

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