aeron-io/aeron · error

AERON_ERROR_CODE_UNKNOWN_COMMAND_TYPE_ID

AERON_ERROR_CODE_UNKNOWN_COMMAND_TYPE_ID

Error message

command={msg_type_id} unknown

What it means

The C media driver's conductor command dispatcher (aeron_driver_conductor_on_rb_command) received a message on the driver-to-client or client-to-driver broadcast/ring buffer whose msg_type_id does not match any known command. It records the error via AERON_SET_ERR with AERON_ERROR_CODE_UNKNOWN_COMMAND_TYPE_ID and logs it, then continues.

Solutions

1. Upgrade the media driver binary to match the client library version.
2. Delete stale shared-memory files (/dev/shm/aeron-*) and restart driver and clients together.
3. Ensure all processes use the same Aeron protocol version.
4. If persistent, check for out-of-bounds writes corrupting the command ring buffer.

Example fix

# before: driver at v1.40, client at v1.45 -> unknown command
$ aeron-media-driver &
# after: versions aligned and stale buffers cleared
$ rm -f /dev/shm/aeron-*
$ aeron-media-driver-1.45 &
$ my-aeron-client-1.45

if (aeron_version_get_semantic_version() ... /* compare driver & client versions before connect */) { fprintf(stderr, "version mismatch: driver=%s client=%s\n", drvVer, cliVer); exit(1); }

static bool is_known_command_type_id(int64_t type_id) { switch (type_id) { case AERON_COMMAND_...: return true; default: return false; } } // validate ids your client sends

if (aeron_errcode() == -AERON_ERROR_CODE_UNKNOWN_COMMAND_TYPE_ID) { fprintf(stderr, "driver rejected command: %s\n", aeron_errmsg()); /* align versions, restart */ } else if (aeron_errcode() != 0) { fprintf(stderr, "aeron error: %s\n", aeron_errmsg()); }

When it happens

Trigger: A client library version sends a command type id the driver does not know (protocol version mismatch), or the ring buffer is corrupted/replayed at a wrong offset so an arbitrary integer is read as msg_type_id.

Common situations: Mixing a newer Aeron C/C++/Java client with an older C media driver binary; stale shared-memory files (/dev/shm) left by a previous run with a different protocol version; memory corruption from a rogue writer.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• AERON_ERROR_CODE_MALFORMED_COMMAND
• AeronCluster.Context ingressEndpoints must be null when…
• uses the same id as
• Driver events adapter is invalid
• exceeded session limit, streamId=

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

Appendix: source

Thrown at aeron-driver/src/main/c/aeron_driver_conductor.c:3200

        case AERON_COMMAND_GET_NEXT_AVAILABLE_SESSION_ID:
        {
            aeron_get_next_available_session_id_command_t *command = (aeron_get_next_available_session_id_command_t *)message;

            if (length < sizeof(aeron_get_next_available_session_id_command_t))
            {
                goto malformed_command;
            }

            correlation_id = command->correlated.correlation_id;

            aeron_driver_conductor_on_get_next_available_session_id(conductor, command);
            break;
        }

        default:
            AERON_SET_ERR(-AERON_ERROR_CODE_UNKNOWN_COMMAND_TYPE_ID, "command=%d unknown", msg_type_id);
            aeron_driver_conductor_log_error(conductor);
            break;
    }

    if (result < 0)
    {
        aeron_driver_conductor_on_error(conductor, aeron_errcode(), aeron_errmsg(), correlation_id);
    }

    return AERON_RB_CONTINUE;

malformed_command:
    AERON_SET_ERR(
        -AERON_ERROR_CODE_MALFORMED_COMMAND, "command=%d too short: length=%" PRIu64, msg_type_id, (uint64_t)length);
    aeron_driver_conductor_log_error(conductor);

    return AERON_RB_CONTINUE;
}

View on GitHub (pinned to 6d60124e15)