apache/pulsar · error · IllegalArgumentException

description should be at most 64 characters

Error message

description should be at most 64 characters

What it means

IllegalArgumentException enforcing that the admin client's optional user-agent description is at most 64 characters. The description is stored in ClientConfigurationData and sent with requests (e.g. for tracing); longer values are rejected immediately by the builder rather than by the server.

Source

Thrown at pulsar-client-admin/src/main/java/org/apache/pulsar/client/admin/internal/PulsarAdminBuilderImpl.java:416

    @Override
    public PulsarAdminBuilder maxConnectionsPerHost(int maxConnectionsPerHost) {
        // reuse the same configuration as the client, however for the admin client, the connection
        // is usually established to a cluster address and not to a broker address
        this.conf.setConnectionsPerBroker(maxConnectionsPerHost);
        return this;
    }

    @Override
    public PulsarAdminBuilder connectionMaxIdleSeconds(int connectionMaxIdleSeconds) {
        this.conf.setConnectionMaxIdleSeconds(connectionMaxIdleSeconds);
        return this;
    }

    @Override
    public PulsarAdminBuilder description(String description) {
        if (description != null && description.length() > 64) {
            throw new IllegalArgumentException("description should be at most 64 characters");
        }
        this.conf.setDescription(description);
        return this;
    }

    @Override
    public PulsarAdminBuilder socks5ProxyAddress(InetSocketAddress socks5ProxyAddress) {
        this.conf.setSocks5ProxyAddress(socks5ProxyAddress);
        return this;
    }

    @Override
    public PulsarAdminBuilder socks5ProxyUsername(String socks5ProxyUsername) {
        this.conf.setSocks5ProxyUsername(socks5ProxyUsername);
        return this;
    }

    @Override

View on GitHub (pinned to 820761864e)

Solutions

1. Shorten the description to 64 characters or fewer before calling description().
2. Truncate programmatically: description.length() > 64 ? description.substring(0, 64) : description.
3. Pass null to omit the description if it isn't needed.

Example fix

// before
adminBuilder.description("My Long Application Name v1.2.3 environment=production cluster=us-east region=primary");
// after
String desc = "MyApp v1.2.3 production";
adminBuilder.description(desc.length() > 64 ? desc.substring(0, 64) : desc);

public static PulsarAdminBuilder safeDescription(PulsarAdminBuilder b, String d) {
    if (d != null && d.length() > 64)
        throw new IllegalArgumentException("description must be <= 64 chars, got " + d.length());
    return b.description(d);
}

try {
    builder.description(desc);
} catch (IllegalArgumentException e) {
    builder.description(desc.substring(0, 64));
}

When it happens

Trigger: Calling PulsarAdminBuilder.description(String) with a non-null string longer than 64 characters.

Common situations: Passing an app name plus version plus environment string concatenated at runtime; building the description from a long config value or hostname; forgetting that the 64-char limit applies to this builder field.

Related errors

• failoverThreshold must be larger than 0
• recoverThreshold must be larger than 0
• checkHealthyIntervalMs must be larger than 0
• testTopic can not be blank
• pulsarServiceUrlArray can not be empty

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