aeron-io/aeron · error · ClusterException

invalid cluster member id, must be an integer value

Error message

invalid cluster member id, must be an integer value

What it means

Within ClusterMember.parse, the first attribute of each member entry must parse as an integer cluster member id. A NumberFormatException is converted into this ClusterException (with the original as cause).

Solutions

1. Ensure each member entry begins with its integer cluster member id
2. Check for stray/missing commas that shift field positions
3. Validate the members string format before deployment
4. Enable a startup config validation that calls ClusterMember.parse early

Example fix

// before
"alpha,localhost:20000,localhost:20001,localhost:20002,localhost:20003,localhost:20004"
// after
"0,localhost:20000,localhost:20001,localhost:20002,localhost:20003,localhost:20004"

boolean hasIntegerId(String entry) {
    String first = entry.split(",")[0].trim();
    try { Integer.parseInt(first); return true; } catch (NumberFormatException e) { return false; }
}

try {
    ClusterMember.parse(membersString);
} catch (ClusterException e) {
    if (e.getCause() instanceof NumberFormatException) {
        log.error("member id field is not an integer", e);
    }
}

When it happens

Trigger: A member entry in the members string starts with a non-integer field (e.g. hostname in place of the id, or a stray comma shifting fields so the id position holds text).

Common situations: Config strings like "node0,host:..." or a missing id field causing endpoint values to land in the id slot.

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

• invalid member value
• invalid member value
• invalid entity tag, must be a number
• empty key not allowed at index
• invalid end of key at index

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/ClusterMember.java:573

        for (int i = 0; i < length; i++)
        {
            final String idAndEndpoints = memberValues[i];
            final String[] memberAttributes = idAndEndpoints.split(",");

            if (memberAttributes.length < 6 || 8 < memberAttributes.length)
            {
                throw new ClusterException("invalid member value: " + idAndEndpoints + " within: " + value);
            }

            final int clusterMemberId;
            try
            {
                clusterMemberId = Integer.parseInt(memberAttributes[0]);
            }
            catch (final NumberFormatException ex)
            {
                throw new ClusterException("invalid cluster member id, must be an integer value", ex);
            }

            final String archiveResponseEndpoint = 6 < memberAttributes.length ? memberAttributes[6] : null;
            final String egressResponseEndpoint = 7 < memberAttributes.length ? memberAttributes[7] : null;

            String endpoints = String.join(
                ",",
                memberAttributes[1],
                memberAttributes[2],
                memberAttributes[3],
                memberAttributes[4],
                memberAttributes[5]);

            if (null != archiveResponseEndpoint)
            {
                endpoints += "," + archiveResponseEndpoint;
            }

View on GitHub (pinned to 6d60124e15)