aeron-io/aeron · error · ControlProtocolException

MALFORMED_COMMAND

MALFORMED_COMMAND

Error message

command={msgTypeId} too short: length={length}

What it means

StaticCounterMessageFlyweight.validateLength first checks the command meets the fixed MINIMUM_LENGTH (registration id + counters etc.). A shorter buffer means the fixed header fields cannot be decoded, so ControlProtocolException(MALFORMED_COMMAND) is thrown before variable parts (label/key) are examined.

Solutions

1. Allocate and report at least StaticCounterMessageFlyweight.MINIMUM_LENGTH bytes for the command.
2. Prefer the AeronClient's high-level Counter APIs (Aeron.addCounter) instead of writing raw flyweights.
3. Align client and driver versions so the STATIC_COUNTER layout matches.
4. Call validateLength immediately after encoding to fail fast with a clear message.

Example fix

// before
UnsafeBuffer buf = new UnsafeBuffer(new byte[16]);
// after
UnsafeBuffer buf = new UnsafeBuffer(new byte[Math.max(StaticCounterMessageFlyweight.MINIMUM_LENGTH, computedLength)]);

if (buffer.capacity() < StaticCounterMessageFlyweight.MINIMUM_LENGTH) { throw new IllegalArgumentException("buffer too small for static counter command"); }

try { counter = aeron.addCounter(typeId, keyBuffer, keyOffset, keyLength, label); } catch (ControlProtocolException e) { /* handle MALFORMED_COMMAND */ }

When it happens

Trigger: Publishing a STATIC_COUNTER command to the driver whose total length is below MINIMUM_LENGTH, e.g. truncating the buffer before write or a corrupted control message.

Common situations: Hand-rolled command encoding with wrong capacity, driver/client version skew changing the fixed layout, or corrupted Aeron Cnc file replayed from disk.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• MALFORMED_COMMAND
• MALFORMED_COMMAND
• MALFORMED_COMMAND
• MALFORMED_COMMAND
• MALFORMED_COMMAND

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/command/StaticCounterMessageFlyweight.java:250

     * @return the length of the current message
     */
    public int length()
    {
        final int labelOffset = labelLengthOffset();
        return labelOffset + SIZE_OF_INT + labelBufferLength();
    }

    /**
     * Validate buffer length is long enough for message.
     *
     * @param msgTypeId type of message.
     * @param length    of message in bytes to validate.
     */
    public void validateLength(final int msgTypeId, final int length)
    {
        if (length < MINIMUM_LENGTH)
        {
            throw new ControlProtocolException(
                MALFORMED_COMMAND, "command=" + msgTypeId + " too short: length=" + length);
        }

        final int labelOffset = labelLengthOffset();
        if ((length - labelOffset) < SIZE_OF_INT)
        {
            throw new ControlProtocolException(
                MALFORMED_COMMAND, "command=" + msgTypeId + " too short for key: length=" + length);
        }

        final int encodedLength = length();
        if (length < encodedLength)
        {
            throw new ControlProtocolException(
                MALFORMED_COMMAND,
                "command=" + msgTypeId + " too short for label: length=" + length + " encodedLength=" + encodedLength);
        }
    }

View on GitHub (pinned to 6d60124e15)