apache/pulsar · error · IllegalArgumentException

connectionsPerBroker must be >= 1

Error message

connectionsPerBroker must be >= 1

What it means

ConnectionPolicy requires connectionsPerBroker >= 1 because it controls how many TCP connections the client opens to each broker; zero or negative values would prevent any connection from being established. The constructor throws IllegalArgumentException when a smaller value is supplied.

Source

Thrown at pulsar-client-api-v5/src/main/java/org/apache/pulsar/client/api/v5/config/ConnectionPolicy.java:64

    private final ProxyProtocol proxyProtocol;
    private final BackoffPolicy connectionBackoff;

    private ConnectionPolicy(Duration connectionTimeout,
                             int connectionsPerBroker,
                             boolean enableTcpNoDelay,
                             Duration keepAliveInterval,
                             Duration connectionMaxIdleTime,
                             int ioThreads,
                             int callbackThreads,
                             String proxyServiceUrl,
                             ProxyProtocol proxyProtocol,
                             BackoffPolicy connectionBackoff) {
        Objects.requireNonNull(connectionTimeout, "connectionTimeout must not be null");
        Objects.requireNonNull(keepAliveInterval, "keepAliveInterval must not be null");
        Objects.requireNonNull(connectionMaxIdleTime, "connectionMaxIdleTime must not be null");
        Objects.requireNonNull(connectionBackoff, "connectionBackoff must not be null");
        if (connectionsPerBroker < 1) {
            throw new IllegalArgumentException("connectionsPerBroker must be >= 1");
        }
        if (ioThreads < 1) {
            throw new IllegalArgumentException("ioThreads must be >= 1");
        }
        if (callbackThreads < 1) {
            throw new IllegalArgumentException("callbackThreads must be >= 1");
        }
        this.connectionTimeout = connectionTimeout;
        this.connectionsPerBroker = connectionsPerBroker;
        this.enableTcpNoDelay = enableTcpNoDelay;
        this.keepAliveInterval = keepAliveInterval;
        this.connectionMaxIdleTime = connectionMaxIdleTime;
        this.ioThreads = ioThreads;
        this.callbackThreads = callbackThreads;
        this.proxyServiceUrl = proxyServiceUrl;
        this.proxyProtocol = proxyProtocol;
        this.connectionBackoff = connectionBackoff;
    }

View on GitHub (pinned to 820761864e)

Solutions

1. Set connectionsPerBroker to at least 1; omit the call to keep the library default.
2. Fix the calculation producing 0 and clamp: Math.max(1, value).
3. Treat 0 in config as 'use default' instead of passing it through.

Example fix

// before
ConnectionPolicy cp = ConnectionPolicy.builder()
    .connectionsPerBroker(0) // IllegalArgumentException
    .build();

// after
ConnectionPolicy cp = ConnectionPolicy.builder()
    .connectionsPerBroker(1)
    .build();

int c = Math.max(1, configuredConnectionsPerBroker);
ConnectionPolicy cp = ConnectionPolicy.builder().connectionsPerBroker(c).build();

static boolean isValidConnectionsPerBroker(int v) { return v >= 1; }

try {
    cp = ConnectionPolicy.builder().connectionsPerBroker(cfg).build();
} catch (IllegalArgumentException e) {
    log.warn("Invalid connectionsPerBroker, using default", e);
    cp = ConnectionPolicy.builder().build();
}

When it happens

Trigger: Calling ConnectionPolicy.builder().connectionsPerBroker(0) or a negative number; computing the value from config or a formula that yields 0 (e.g. an empty pool calculation).

Common situations: Using 0 as 'unlimited' or 'default' sentinel; parsing an empty/blank config string into 0; a sizing algorithm dividing counts that returns 0 for small workloads.

Understand the failure class

Background: "Invalid configuration value" and "Unsupported/Unknown setting value" errors: why libraries reject your config strings, numbers, and types — this error's family across 30 libraries.

Related errors

• jitterPercent must be in [0, 100]
• configuredService should not be an instance of SystemTopicBa
• The shared resource doesn't support thread pool configurati
• No resources have been configured while using shareConfigure
• maxMessages must be >= 0

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/a5722c82b0595a26. Report an issue: GitHub.