apache/cassandra · error · IllegalArgumentException

Beta version of server used

Error message

Beta version of server used (%s), but USE_BETA flag is not set

What it means

Thrown by SimpleClient.Builder.build() when the caller requests a beta protocol version without setting the USE_BETA startup flag. The CQL binary protocol requires clients to explicitly opt in (USE_BETA flag in STARTUP) when speaking a beta protocol version; this client-side guard fails fast with an IllegalArgumentException before any connection is made.

Solutions

1. Set useBeta(true) on the SimpleClient.Builder when using a beta protocol version
2. Or pin the client to the latest non-beta ProtocolVersion
3. Upgrade to a server build where the version you need is no longer beta, then drop the flag
4. Only enable beta in test environments — it is not meant for production clients

Example fix

// before
SimpleClient.builder(host, port).version(ProtocolVersion.V5).build();
// after (V5 beta era)
SimpleClient.builder(host, port).version(ProtocolVersion.V5).useBeta(true).build();

if (version.isBeta() && !useBeta)
    throw new IllegalArgumentException("set useBeta(true) on the builder or use a non-beta ProtocolVersion");

boolean safeClientVersion(ProtocolVersion v) { return !v.isBeta(); }

try { client = builder.build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("USE_BETA")) builder.useBeta(true).build(); else throw e; }

When it happens

Trigger: Builder configured with a beta ProtocolVersion (e.g. the latest in-development version) but useBeta left false; build() checks version.isBeta() && !useBeta and throws.

Common situations: Testing against a dev/bleeding-edge server with a beta protocol, copying test-client code that pins a version that has since become beta, or forgetting the flag when explicitly bumping the client's protocol version.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• appendAll() can only be called on non-frozen collections
• Cannot decode string as UTF8: '" +…
• Cannot read value of length
• Invalid ByteBuf length " + length
• Invalid value ' ' for

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/1099637a41ca522a. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/transport/SimpleClient.java:168

            return this;
        }

        public Builder protocolVersion(ProtocolVersion version)
        {
            this.version = version;
            return this;
        }

        public Builder largeMessageThreshold(int bytes)
        {
            largeMessageThreshold = bytes;
            return this;
        }

        public SimpleClient build()
        {
            if (version.isBeta() && !useBeta)
                throw new IllegalArgumentException(String.format("Beta version of server used (%s), but USE_BETA flag is not set", version));
            return new SimpleClient(this);
        }
    }

    public static Builder builder(String host, int port)
    {
        return new Builder(host, port);
    }

    private SimpleClient(Builder builder)
    {
        this.host = builder.host;
        this.port = builder.port;
        this.version = builder.version;
        this.encryptionOptions = builder.encryptionOptions.applyConfig();
        this.largeMessageThreshold = builder.largeMessageThreshold;
    }

View on GitHub (pinned to 88fd0f6a0e)