ConnectorsKafkaReference
Error Codes
The Kafka protocol error codes the connector returns — UNSUPPORTED_VERSION, INVALID_PARTITIONS, transaction, authorization and share-group codes.
The KubeMQ Kafka connector answers every failure with a standard Kafka protocol error
code — the same numeric ErrorCode field (top-level, per-partition, or per-resource,
depending on the API) a stock Kafka client already knows how to interpret. There is no
custom error vocabulary: branch your client's retry/reconfigure logic on the numeric code
exactly as you would against real Kafka.
Retriable vs. non-retriable. Codes marked retriable reflect a transient condition — the broker isn't ready, a race was lost, a coordinator pointer is stale — that a client's normal backoff-and-retry resolves. Non-retriable means resending the identical request will never succeed; something has to change first.
Version negotiation
| Code | Error | What triggers it |
|---|---|---|
| 35 | UNSUPPORTED_VERSION | The request's version falls outside that key's advertised [min, max] window (see Capabilities). Encoded at the key's max version so the client can parse it and renegotiate via ApiVersions. |
Produce and fetch (data plane)
| Code | Error | What triggers it |
|---|---|---|
| 1 | OFFSET_OUT_OF_RANGE | Fetch/ListOffsets requested an offset below the log start or above the high watermark — never used for a valid empty fetch at offset 0. Non-retriable at that offset. |
| 2 | CORRUPT_MESSAGE | A Produce batch failed decode — CRC mismatch, an incomplete/oversized batch, a bad Magic byte, or a negative FirstSequence from an idempotent producer. Non-retriable. |
| 3 | UNKNOWN_TOPIC_OR_PARTITION | The topic or partition doesn't exist and auto-create didn't apply. This includes a Metadata lookup that asked not to auto-create — AdminClient's describeTopics, and librdkafka consumers by default — for a topic that does not exist. A producer's lookup still auto-creates on first write, as Apache Kafka's auto.create.topics.enable does. |
| 5 | LEADER_NOT_AVAILABLE | The broker isn't accepting traffic yet — still starting, or a just-promoted leader catching up on Raft. Retriable. |
| 6 | NOT_LEADER_OR_FOLLOWER | A clustered follower answers this on Fetch so the client's metadata refresh re-routes it to the leader. Retriable. |
| 10 | MESSAGE_TOO_LARGE | A Produce partition's Records exceed MaxMessageBytes (default 1 MiB), or the whole request exceeds MaxRequestBytes (default 100 MiB), in which case every partition in it carries this code and the connection stays open. Non-retriable — the producer must reconfigure. |
| 17 | INVALID_TOPIC_EXCEPTION | The topic name fails KubeMQ's channel-name validation — kept distinct from an authorization deny so it never leaks "denied" to an unauthorized caller. |
| 21 | INVALID_REQUIRED_ACKS | Produce's Acks is set to something other than 0, 1, or -1. Unreachable by a conformant client. Non-retriable. |
| 45 | OUT_OF_ORDER_SEQUENCE_NUMBER | An idempotent producer's per-(PID, partition) sequence check found a gap. |
| 46 | DUPLICATE_SEQUENCE_NUMBER | The same (PID, partition) sequence was already accepted — the connector dedups the retry. |
| 59 | UNKNOWN_PRODUCER_ID | The batch's producer ID has no live sequence-tracking record — expired, or never seen. |
| 74 | FENCED_LEADER_EPOCH | The client's CurrentLeaderEpoch is older than the partition's live epoch. Retriable. |
| 75 | UNKNOWN_LEADER_EPOCH | The client's CurrentLeaderEpoch is newer than what this node knows. Retriable. |
| 100 | UNKNOWN_TOPIC_ID | A Metadata v10+ request named a TopicID (KIP-516) that doesn't resolve to any discoverable topic. |
Consumer-group coordinator
| Code | Error | What triggers it |
|---|---|---|
| 14 | COORDINATOR_LOAD_IN_PROGRESS | The durable offset store hasn't finished replaying at boot. Retriable — a background sweep retries until it succeeds. |
| 15 | COORDINATOR_NOT_AVAILABLE | The broker isn't accepting group-coordinator traffic yet. Retriable. |
| 16 | NOT_COORDINATOR | This node isn't the caught-up Raft leader for the group; surfaces only when the leader-proxy hop fails. Retriable. |
| 22 | ILLEGAL_GENERATION | A Join/Sync/Heartbeat names a generation the coordinator has already moved past. |
| 23 | INCONSISTENT_GROUP_PROTOCOL | The group's members can't agree on a common protocol/assignor during a rebalance. |
| 24 | INVALID_GROUP_ID | A group.id no KubeMQ consumer could join: empty, longer than 249 bytes, not valid UTF-8, containing /, * or >, with a leading or trailing dot, or containing ... Answered by JoinGroup, Heartbeat, SyncGroup, LeaveGroup, OffsetCommit, OffsetFetch, AddOffsetsToTxn and TxnOffsetCommit. Non-retriable. |
| 25 | UNKNOWN_MEMBER_ID | The presented member.id is unknown — never joined, already reaped, or an unrecognized static-instance mapping. |
| 26 | INVALID_SESSION_TIMEOUT | JoinGroupRequest.SessionTimeoutMillis falls outside the coordinator's accepted bounds. |
| 27 | REBALANCE_IN_PROGRESS | The group is (now) rebalancing — the member must rejoin. |
| 68 | NON_EMPTY_GROUP | DeleteGroups targeted a non-Empty group, or OffsetDelete targeted an active non-consumer-protocol group. |
| 69 | GROUP_ID_NOT_FOUND | The named group is unknown to the registry and the durable offset store, or its state is Dead. |
| 79 | MEMBER_ID_REQUIRED | KIP-394's two-round JoinGroup handshake: an empty-MemberID round-1 request (v4+) gets a freshly minted ID and this code; the client resends with it. |
| 81 | GROUP_MAX_SIZE_REACHED | The group, or the coordinator-wide group cap, is already at its configured ceiling. |
| 82 | FENCED_INSTANCE_ID | KIP-345 static membership: group.instance.id maps to a different member.id than the requester — a displaced or duplicate static instance. |
| 86 | GROUP_SUBSCRIBED_TO_TOPIC | OffsetDelete targeted a (topic, partition) a live member still subscribes to — deleting it would rewind that consumer. |
| 88 | UNSTABLE_OFFSET_COMMIT | OffsetFetch set RequireStable (v7+) while the group holds a staged, uncommitted transactional offset. Retriable. |
Topic and partition admin
| Code | Error | What triggers it |
|---|---|---|
| 36 | TOPIC_ALREADY_EXISTS | CreateTopics named a topic that already exists. |
| 37 | INVALID_PARTITIONS | CreatePartitions requested a same-or-lower count, or one above the 256-partition cap; also CreateTopics's NumPartitions over that cap. |
| 38 | INVALID_REPLICATION_FACTOR | A CreateTopics asked for more replicas than there are nodes (Replication factor: 3 larger than available brokers: 1.), or for 0 or a negative value other than -1 — the same rule as Apache Kafka. Any value up to the node count is accepted. |
| 40 | INVALID_CONFIG | An unsupported config value — an invalid cleanup.policy, message.timestamp.type=LogAppendTime, or an APPEND/SUBTRACT op on a scalar config. |
| 41 | NOT_CONTROLLER | An admin write landed on a node that isn't the caught-up leader. Retriable — the client retries against the controller. |
| 42 | INVALID_REQUEST | A malformed field — most commonly a present-but-empty transactional.id, or one failing channel-name validation. |
Transactions
| Code | Error | What triggers it |
|---|---|---|
| 47 | INVALID_PRODUCER_EPOCH | A Produce arrived with an epoch below the live epoch on record — a zombie holding a stale epoch. Non-retriable; the producer must re-run InitProducerId. |
| 48 | INVALID_TXN_STATE | A transactional batch arrived in the wrong coordinator state; also reused by AddPartitionsToTxn/AddOffsetsToTxn/EndTxn/TxnOffsetCommit for their own state violations. |
| 49 | INVALID_PRODUCER_ID_MAPPING | A KIP-360 request named a (transactional.id, PID) pair with no durable record — the ID is new, or was tombstoned since the client last saw it. |
| 50 | INVALID_TRANSACTION_TIMEOUT | TransactionTimeoutMillis is <= 0 or exceeds the coordinator-wide ceiling. |
| 51 | CONCURRENT_TRANSACTIONS | Two state/epoch-transition attempts raced for the same transactional.id. Retriable. |
| 53 | TRANSACTIONAL_ID_AUTHORIZATION_FAILED | The principal lacks Write on the transactional.id resource. |
| 55 | OPERATION_NOT_ATTEMPTED | AddPartitionsToTxn named a partition that doesn't exist alongside ones that do — the existing ones answer this instead of a false success. |
| 87 | INVALID_RECORD | A client submitted a control batch — those are broker-internal; the only real producer is the coordinator's own commit/abort marker. |
| 90 | PRODUCER_FENCED | A KIP-360 InitProducerId epoch is strictly above the live durable epoch — the only branch that answers 90. |
KIP-890 transaction protocol V2 is not shipped — no per-EndTxn epoch bump. EndTxn
writes a real in-log COMMIT/ABORT marker, but soundness stays bounded to the V1 wire scope in
Capabilities.
Authorization
| Code | Error | What triggers it |
|---|---|---|
| 29 | TOPIC_AUTHORIZATION_FAILED | The principal lacks the required topic ACL — Produce needs Write; Fetch/ListOffsets/OffsetFetch need Read. |
| 30 | GROUP_AUTHORIZATION_FAILED | The principal lacks the required group ACL — OffsetCommit/OffsetDelete/DeleteGroups need Write; Join/Sync/Heartbeat/Leave/DescribeGroups need Read. |
| 31 | CLUSTER_AUTHORIZATION_FAILED | The principal lacks Describe on the cluster resource — e.g. DescribeCluster(60). |
Every authorization deny above is non-retriable — re-authenticate or request a policy grant rather than retry unchanged.
SASL
| Code | Error | What triggers it |
|---|---|---|
| 33 | UNSUPPORTED_SASL_MECHANISM | The client's SASLHandshake names a mechanism this listener doesn't offer — for example, OAUTHBEARER on the plaintext listener (TLS-only). The response still lists supported mechanisms; the connection stays open. |
| 34 | ILLEGAL_SASL_STATE | SASLAuthenticate arrived before a successful SASLHandshake selected a mechanism. |
| 58 | SASL_AUTHENTICATION_FAILED | Credentials didn't validate — unknown user or wrong password/token, deliberately indistinguishable to the client. The connection is closed. |
Security and resource admin
| Code | Error | What triggers it |
|---|---|---|
| 54 | SECURITY_DISABLED | A SCRAM-credential or ACL mutation was refused — both are config-managed (Connectors.Kafka.Credentials), not runtime-mutable. Also answered when authorization is off entirely. |
| 61 | DELEGATION_TOKEN_AUTH_DISABLED | Any delegation-token request — KubeMQ does not implement delegation tokens; switch those principals to SASL/SCRAM or mTLS. |
| 91 | RESOURCE_NOT_FOUND | DescribeUserScramCredentials named a user with no SCRAM credentials configured. Non-retriable. |
Share groups
| Code | Error | What triggers it |
|---|---|---|
| 15 | COORDINATOR_NOT_AVAILABLE | Creating one more share group than CONNECTORS_KAFKA_MAX_GROUPS allows — by a first join or by setting a new group's start offsets. Nothing is created. Retriable; it succeeds once unused share groups are deleted or the cap is raised. |
| 24 | INVALID_GROUP_ID | ShareGroupHeartbeat or AlterShareGroupOffsets named a group id no KubeMQ consumer could join (containing /, * or >, a leading or trailing dot, .., or empty) or one that is not valid UTF-8. The classic group APIs refuse the same ids — see Consumer-group coordinator. Nothing is stored. Non-retriable. |
| 35 | UNSUPPORTED_VERSION | While CONNECTORS_KAFKA_SHARE_FEATURE_VERSION is 1 (a rolling-upgrade setting): deleting a share group, or AlterShareGroupOffsets creating a group's first start offset. |
| 40 | INVALID_CONFIG | A lock-duration, session-timeout or heartbeat-interval value outside its allowed range; an invalid share.auto.offset.reset or share.isolation.level value; an unknown group config key; an APPEND or SUBTRACT operation; or any change to share.assignment.interval.ms. The delivery-count limit and the record-lock cap are clamped into range, never refused — see Per-group configuration. |
| 44 | POLICY_VIOLATION | A per-group share config write (kafka-configs.sh --entity-type groups) that would give one more group stored configuration than CONNECTORS_KAFKA_MAX_GROUPS allows. Nothing is written. Non-retriable: stored group configuration is never removed, so only raising the cap lets the write succeed. A group that already holds configuration is never subject to the cap. |
| 42 | INVALID_REQUEST | Acknowledgement ranges that overlap, run backwards, or start below zero (none of that partition's acknowledgements are applied); a group id that is not valid UTF-8 on ShareFetch, ShareAcknowledge or a group-config request; and, while CONNECTORS_KAFKA_SHARE_FEATURE_VERSION is 1, a read_committed group's fetch or any group-config write. |
| 68 | NON_EMPTY_GROUP | DeleteGroups, AlterShareGroupOffsets or DeleteShareGroupOffsets on a share group that still has a consumer attached. Stop the consumer, then retry. |
| 69 | GROUP_ID_NOT_FOUND | The group id is in use as the other group type — a share-group request for a classic group (message "Group X is not a share group."), or JoinGroup/OffsetCommit/TxnOffsetCommit for a share group. Non-retriable. |
| 121 | INVALID_RECORD_STATE | An Accept, Release or Reject for a record another consumer now holds (nothing is applied); a renew for a record this consumer does not currently hold (released, lock expired, already acknowledged, or never acquired); or any renew when the group sets share.renew.acknowledge.enable=false or CONNECTORS_KAFKA_SHARE_FEATURE_VERSION is 1. |
| 123 | INVALID_SHARE_SESSION_EPOCH | A ShareFetch arrived for a share session the broker no longer holds — a failover, or the session was reaped — or named a member or session the coordinator has never seen. The client resets and reopens at epoch 0. |
A late acknowledgement for a record nobody holds any more is not refused 121 on KubeMQ,
where Kafka refuses it — see
the share-group differences.
Related
Capabilities
Every implemented Kafka API key, its version range, and its support status.
Limits & Rules
The numeric ceilings — partitions, message size, connections, groups — several of these codes enforce.
Transactions & EOS
Handling the transaction-coordinator error codes in a transactional producer.
Authentication
SASL/SCRAM, OAUTHBEARER, and mTLS — and the errors each failure mode returns.
Was this page helpful?
Topic Mapping
How Kafka topics, partitions, and offsets map to KubeMQ — the kafka.{topic} Events Store log, the ~{partition} suffix, and the offset-to-Sequence off-by-one.
Limits & Rules
The Kafka connector's numeric limits — 256 partitions per topic, the 1 MiB default message ceiling, connection and consumer-group caps, and offset retention.