aeron-io/aeron · critical · IllegalStateException

uses the same id as

Error message

${descriptor} uses the same id as ${other}

What it means

SystemCounterDescriptor's static initializer registers every enum constant in DESCRIPTOR_BY_ID_MAP and throws IllegalStateException if two descriptors share the same counter id. This is a startup self-check protecting the internal invariant that counter ids are unique; normal users only hit it if they modified the enum or use a patched build.

Solutions

1. Assign the new descriptor a unique id not used by any existing SystemCounterDescriptor.
2. Check the classpath for duplicate or mismatched Aeron jars and remove the stale one.
3. If you did not modify the code, report it as a bug with the full stack trace and jar versions.

Example fix

// before
NEW_COUNTER("duplicate-id-conflict", ...); // id already used
// after
NEW_COUNTER("unique-unused-id", ...); // allocate a fresh id

try { /* trigger class init / driver start */ } catch (IllegalStateException e) { if (e.getMessage().contains("uses the same id as")) { log.error("Classpath corruption or patched enum with duplicate counter id", e); } throw e; }

When it happens

Trigger: Adding or duplicating a SystemCounterDescriptor enum constant with an id already used by another constant, or binary-patching/incompatible class transformation that collides ids.

Common situations: Custom forks of Aeron adding new system counters without allocating a fresh id; mixing mismatched aeron-driver/aeron-client jar versions on the classpath.

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

• invalid port value
• :low port value must be lower than high port value
• no available ports in range
• :port must be an integer value between 0 and 65535
• Property = is not a number

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/status/SystemCounterDescriptor.java:365

     */
    NATIVE_RESOURCE_AGENT_PROXY_FAILS(
        SYSTEM_COUNTER_ID_NATIVE_RESOURCE_AGENT_PROXY_FAILS, "Failed offers to NativeResourceAgentProxy");

    /**
     * All system counters have the same type id, i.e. system counters are the same type. Other types can exist.
     */
    public static final int SYSTEM_COUNTER_TYPE_ID = AeronCounters.DRIVER_SYSTEM_COUNTER_TYPE_ID;

    private static final Int2ObjectHashMap<SystemCounterDescriptor> DESCRIPTOR_BY_ID_MAP = new Int2ObjectHashMap<>();

    static
    {
        for (final SystemCounterDescriptor descriptor : SystemCounterDescriptor.values())
        {
            final SystemCounterDescriptor other = DESCRIPTOR_BY_ID_MAP.put(descriptor.id, descriptor);
            if (null != other)
            {
                throw new IllegalStateException(descriptor + " uses the same id as " + other);
            }
        }
    }

    /**
     * Get the {@link SystemCounterDescriptor} for a given id.
     *
     * @param id for the descriptor.
     * @return the descriptor if found otherwise null.
     */
    public static SystemCounterDescriptor get(final int id)
    {
        return DESCRIPTOR_BY_ID_MAP.get(id);
    }

    private final int id;
    private final String label;

View on GitHub (pinned to 6d60124e15)