apache/kafka · error · IllegalArgumentException

Node id for group coordinator node cannot be negative

Error message

Node id for group coordinator node cannot be negative

What it means

IllegalArgumentException thrown by GroupCoordinatorNode.validateId when constructing a GroupCoordinatorNode with a negative id. The class deliberately separates the group-coordinator connection identity from a normal broker connection by prepending '+' to the idString; because negative node ids are reserved by the client for bootstrap/unresolved nodes, a negative coordinator id would collide with that namespace and is rejected. This is an internal invariant guard rather than a runtime config check.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/internals/GroupCoordinatorNode.java:38

/**
 * This subclass of {@link Node} is used by the consumer for information about
 * a Kafka node which is a group coordinator. It ensures that the idString differs from
 * a regular node with the same node ID so that the network code can maintain separate
 * network connections to the same node as a regular broker and as a group coordinator.
 * It achieves this by ensuring that the node ID is non-negative (which it must be because
 * negative node IDs are used for bootstrapping) and by prepending a '+' on the node ID to
 * create the idString. This maintains the requirement that the idString can be parsed as
 * an integer to obtain the actual node ID.
 */
public class GroupCoordinatorNode extends Node {
    public GroupCoordinatorNode(int id, String host, int port) {
        super(GroupCoordinatorNode.validateId(id), host, port, null, false, "+" + id);
    }

    private static int validateId(int id) {
        if (id < 0) {
            throw new IllegalArgumentException("Node id for group coordinator node cannot be negative");
        }
        return id;
    }
}

View on GitHub (pinned to c31c9215e1)

Solutions

1. If calling the constructor directly, ensure the id comes from a valid FindCoordinator response node (always non-negative in well-formed responses).
2. Inspect broker logs and the FindCoordinator response; a negative id indicates broker-side corruption.
3. File a Kafka bug report with the FindCoordinator response contents if it comes from a stock client against a healthy broker.

Example fix

// before
new GroupCoordinatorNode(-1, host, port);

// after
new GroupCoordinatorNode(coordinatorNode.id(), coordinatorNode.host(), coordinatorNode.port());

if (nodeId < 0) {
    throw new IllegalArgumentException("Refusing to build GroupCoordinatorNode with negative id: " + nodeId);
}

private static boolean isAcceptableNodeId(int id) {
    // Broker node ids must be non-negative; negative ids are reserved for bootstrap/seed nodes.
    return id >= 0;
}

When it happens

Trigger: Raised only when GroupCoordinatorNode's constructor is called with id < 0. In practice this is an internal API used during FindCoordinator response handling; it should not occur unless a malformed FindCoordinator response returned a negative node id, or user code instantiates GroupCoordinatorNode directly with a bad id.

Common situations: Effectively never seen from application code. Theoretically possible with a misbehaving broker or a custom NetworkClient plumbing bogus coordinator metadata. If observed it indicates a bug in FindCoordinator response construction or in code wrapping the consumer internals.

Related errors

• Attempt to retrieve value from future which hasn't successfu
• To use the group management or offset commit APIs, you must
• The target time for partition {} is {}. The target time cann
• Failed to get offsets by times in {}ms
• The timeout cannot be negative.

AI-assisted analysis of apache/kafka@c31c9215e1 (2026-08-03). Data as JSON: /data/errors/35f6db159efb24e7.json. Report an issue: GitHub.