aeron-io/aeron · error · IllegalArgumentException

id already in use

Error message

id already in use: <id>

What it means

ClusterEventCode's static initializer registers each enum constant by its id into EVENT_CODE_BY_ID; if two constants share the same id the lookup table entry is already occupied and IllegalArgumentException is thrown. This is an internal invariant of the enum definition, only triggered by editing the enum itself.

Solutions

1. Change the new enum constant's id to an unused unique value
2. Audit all ClusterEventCode ids for duplicates after adding a constant
3. Add a unit test that constructs ClusterEventCode values to surface collisions early

Example fix

// before
FOO(17),
BAR(17); // duplicate id
// after
FOO(17),
BAR(18);

// For contributors: ensure new id is unique
assert java.util.Arrays.stream(ClusterEventCode.values())
    .mapToInt(ClusterEventCode::id).distinct().count()
    == ClusterEventCode.values().length;

When it happens

Trigger: Adding a new ClusterEventCode constant whose id() collides with an existing constant's id; refactoring ids and accidentally duplicating one.

Common situations: Contributors adding new cluster event codes to the Aeron source without checking the id table; merging branches that both introduced the same id.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• <name()> - code must equal ordinal value: code=
• - code must equal ordinal value: code=
• ClusterBackup.Context.sourceType=
• response publication already added
• initial ack already received from service: possible…

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

Appendix: source

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

    START(27);

    static final int EVENT_CODE_TYPE = EventCodeType.CLUSTER.getTypeCode();
    static final ClusterEventCode[] EVENT_CODE_BY_ID;

    private final int id;

    static
    {
        final ClusterEventCode[] codes = ClusterEventCode.values();
        final int maxId = Arrays.stream(codes).mapToInt(ClusterEventCode::id).max().orElse(0);
        EVENT_CODE_BY_ID = new ClusterEventCode[maxId + 1];

        for (final ClusterEventCode code : codes)
        {
            final int id = code.id();
            if (null != EVENT_CODE_BY_ID[id])
            {
                throw new IllegalArgumentException("id already in use: " + id);
            }

            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)
    {

View on GitHub (pinned to 6d60124e15)