What causes "token length must be >= 0: {tokenLength}" in aeron-io/aeron?

Fix the code producing the token length; only pass tokenLength >= 0 (e.g. Math.max(0, bytes.length)).

aeron-io/aeron · error · ConfigurationException

token length must be >= 0

Error message

token length must be >= 0: {tokenLength}

What it means

TerminateDriverFlyweight.computeLength computes the total command size as LENGTH + SIZE_OF_INT + tokenLength. A negative tokenLength has no meaning and would corrupt the encoding, so a ConfigurationException is thrown eagerly. Unlike the protocol checks this happens at encode time on the caller's side.

Solutions

Fix the code producing the token length; only pass tokenLength >= 0 (e.g. Math.max(0, bytes.length)).
If no token is needed, pass 0 rather than a sentinel negative value.
Add an assertion or pre-check on token length before calling computeLength.

Example fix

// before
int len = TerminateDriverFlyweight.computeLength(tokenBytes.length - overhead);
// after
int tokenLen = Math.max(0, tokenBytes == null ? 0 : tokenBytes.length);
int len = TerminateDriverFlyweight.computeLength(tokenLen);

Defensive patterns

Strategy: validation

Validate before calling

if (tokenLength < 0) { throw new IllegalArgumentException("tokenLength must be >= 0"); }
int length = TerminateDriverFlyweight.computeLength(tokenLength);

Try / catch

try { int len = TerminateDriverFlyweight.computeLength(tokenLength); } catch (ConfigurationException e) { /* negative token length */ }

Prevention

Never pass sentinel negative lengths; use 0 for no token
Guard any computed token length with Math.max(0, ...)
Assert token buffer reads succeeded before computing length

When it happens

Trigger: Calling computeLength (or an encoder that uses it, e.g. when terminating a driver with an authentication token) with a negative token buffer length.

Common situations: Bugs where token length is derived from an uninitialized variable or a failed read returning -1; subtracting offsets in the wrong order.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/2717abc2f1dd43b7. Report an issue: GitHub.

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/command/TerminateDriverFlyweight.java:159

        if ((length - MINIMUM_LENGTH) < buffer.getInt(offset + TOKEN_LENGTH_OFFSET))
        {
            throw new ControlProtocolException(
                MALFORMED_COMMAND, "command=" + msgTypeId + " too short for token buffer: length=" + length);
        }
    }

    /**
     * Compute the length of the command message for a given token length.
     *
     * @param tokenLength to be appended to the header.
     * @return the length of the command message for a given token length.
     */
    public static int computeLength(final int tokenLength)
    {
        if (tokenLength < 0)
        {
            throw new ConfigurationException("token length must be >= 0: " + tokenLength);
        }

        return LENGTH + SIZE_OF_INT + tokenLength;
    }
}

View on GitHub (pinned to 6d60124e15)