aeron-io/aeron · error · IllegalArgumentException

no ClusterEventCode for id

Error message

no ClusterEventCode for id: <id>

What it means

ClusterEventCode.get(int id) resolves a numeric event code to the enum; the id is outside the valid table range (negative or >= EVENT_CODE_BY_ID.length), so IllegalArgumentException is thrown. Raised from fromEventCodeId when decoding an event with an unrecognized id.

Solutions

1. Upgrade the aeron-cluster dependency so the enum contains the new event code
2. Validate the event code id against ClusterEventCode values before calling get/fromEventCodeId
3. Handle unknown ids defensively: catch IllegalArgumentException and fall back to logging the raw id
4. If the id comes from a log file, confirm it was produced by a compatible Aeron version

Example fix

// before
ClusterEventCode code = ClusterEventCode.fromEventCodeId(id);
// after
ClusterEventCode code = (id >= 0 && id < ClusterEventCode.values().length)
    ? ClusterEventCode.fromEventCodeId(id)
    : null; // handle unknown code

boolean isValid = id >= 0 && id < ClusterEventCode.values().length;

boolean isKnownEventCode(int id) {
    return id >= 0 && id < ClusterEventCode.values().length
        && ClusterEventCode.get(id) != null; // guarded by try-catch in practice
}

try {
    ClusterEventCode code = ClusterEventCode.fromEventCodeId(id);
} catch (IllegalArgumentException ex) {
    // unknown event code: log raw id
}

When it happens

Trigger: Calling ClusterEventCode.fromEventCodeId (or get) with an id not present in this build's enum table, e.g. an id from a newer Aeron cluster version.

Common situations: Client on older aeron-cluster decoding event codes emitted by a newer cluster; log-analysis tools reading corrupted or foreign event logs.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• ClusterBackup.Context.sourceType=
• id already in use
• <name()> - code must equal ordinal value: code=
• Invalid role counter code
• unsupported time unit

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/logging/ClusterEventCode.java:208

            EVENT_CODE_BY_ID[id] = code;
        }
    }

    ClusterEventCode(final int id)
    {
        this.id = id;
    }

    /**
     * Get the ClusterEventCode enum value from the identifier.
     * @param id to look up.
     * @return the resolved enum value.
     */
    public static ClusterEventCode get(final int id)
    {
        if (id < 0 || id >= EVENT_CODE_BY_ID.length)
        {
            throw new IllegalArgumentException("no ClusterEventCode for id: " + id);
        }

        final ClusterEventCode code = EVENT_CODE_BY_ID[id];
        if (null == code)
        {
            throw new IllegalArgumentException("no ClusterEventCode for id: " + id);
        }

        return code;
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public int id()
    {
        return id;

View on GitHub (pinned to 6d60124e15)