aeron-io/aeron · error · ControlProtocolException

MALFORMED_COMMAND

MALFORMED_COMMAND

Error message

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

What it means

A publication-related control command arrived with a total length below the fixed MINIMUM_LENGTH required by PublicationMessageFlyweight. validateLength() throws ControlProtocolException(MALFORMED_COMMAND), aborting the command because even the fixed header fields would not fit.

Solutions

1. Run matching Aeron client and driver versions.
2. Use the flyweight's computeLength() API instead of manual byte counts when emitting commands.
3. Inspect driver event logs to capture the malformed command and locate its producer.
4. Ensure the full command frame is written atomically to the control stream with no truncation.

Example fix

// before
int length = 8; // guessed header size
// after
int length = PublicationMessageFlyweight.computeLength(encodedChannel.length());

if (length < PublicationMessageFlyweight.MINIMUM_LENGTH) { throw new IllegalArgumentException("publication command too short: " + length); }

try { flyweight.validateLength(msgTypeId, length); } catch (ControlProtocolException e) { if (e.errorCode() == ControlProtocolException.MALFORMED_COMMAND) { log.error("Dropping malformed publication command", e); } else { throw e; } }

When it happens

Trigger: An ADD_PUBLICATION / REMOVE_PUBLICATION style command shorter than MINIMUM_LENGTH — truncated write into the driver control buffer, wrong msgTypeId mapping, or a producer that mis-sized the frame.

Common situations: Version mismatch between client and MediaDriver message layouts; custom or buggy command multiplexers; corrupted command queues in shared-memory transports.

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/a1fdd7d18bc54a69. Report an issue: GitHub.

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/command/PublicationMessageFlyweight.java:155

     *
     * @return the length of the current message.
     */
    public int length()
    {
        return CHANNEL_OFFSET + lengthOfChannel;
    }

    /**
     * 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);
        }

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

    /**
     * Compute the length of the command message for a given channel length.
     *
     * @param channelLength to be appended to the header.
     * @return the length of the command message for a given channel length.
     */
    public static int computeLength(final int channelLength)
    {

View on GitHub (pinned to 6d60124e15)