Common Client Errors and Solutions
最終更新日:2025-09-28 16:17:04
Client Configuration or Service Abnormality
The following exception belongs to client configuration or service abnormality, and the client will not retry automatically.
Abnormal | Description | Analysis and Description |
UnknownServerException | An unknown error occurred while the server was processing the request. | Older versions of flow control will return this error; the new version might be due to a server bug. |
RecordTooLargeException | File too large. | Current configuration: message.max.bytes=1000012. |
InvalidRequiredAcksException | The acks parameter in producer configuration is invalid. | - |
InconsistentGroupProtocolException | The Group protocol is inconsistent. | Check whether the Consumer and Connector are configured with the same group.id. They use different protocols and cannot join the same group. |
InvalidGroupIdException | The Consumer Group ID is invalid. | Recommend using [a-zA-Z0-9._-] characters with length not exceeding 128. |
InvalidTopicException | The Topic is invalid. | After enabling the auto-create Topic option, the client will receive this exception if the Topic is invalid. Check whether the Topic contains invalid characters or exceeds the length limit. |
InvalidSessionTimeoutException | The session.timeout.ms in the consumer configuration is invalid. | The current minimum value allowed on the server side is group.min.session.timeout.ms=6000, and the maximum value is group.max.session.timeout.ms=300000. |
InvalidCommitOffsetSizeException | Offset submission is too large, exceeding max message size and cannot be written to __consumer_offsets. | Current configuration: message.max.bytes=1000012. |
OffsetMetadataTooLarge | The Offset submit request contains metadata that is too large. | Server configuration: offset.metadata.max.bytes=4096. |
UnsupportedVersionException | The Broker does not support requests for this version. | It is recommended to use client version 0.10.2.x. |
Program Running Normally with Temporary Exception
The following exception may briefly appear during normal program operation, and the client will retry automatically. If it persists, the service is abnormal.
Abnormal | Description | Analysis and Description |
TimeoutException | Request timeout. | First-time connection reports request timeout. First check whether the address is correct, then use telnet to confirm network connectivity. This exception occasionally thrown during program execution may belong to network jitter. |
CorruptRecordException | The message is invalid. | CRC check may fail due to invalid data size. In addition, if the compression method uses GZip or versions below 0.9 with compression, it may also lead to this error. |
UnknownTopicOrPartitionException | The Topic or Partition does not exist. | Check to console whether the corresponding topic has been created. Note: The client uses TopicName for production consumption rather than TopicId. In addition, the client may report the topic as nonexistent if it has no permission to access it. |
LeaderNotAvailableException | Partition has no Leader. | When a Topic is just created and the server has not yet elected a suitable Leader, this error will be returned to the client. The client will automatically retry to retrieve the Leader info. This issue only occurs in earlier versions and has been removed in 0.10.2.1. |
NotLeaderForPartitionException | The Leader of the Partition is unavailable. | Since the client caches the Topic's Metadata, when the Leader switchover of a Partition occurs, production or consumption requests may still be sent to the old Leader. In this case, this error will be returned to the client, and the client will auto-update the Metadata info. |
NetworkException | The client connection is closed by the server side. | Network exception or the number of connections exceeds the limit. |
NotEnoughReplicasException | Insufficient ISR count. | When writing data, the number of ISRs in the Partition is less than the min.insync.replicas configured for the Topic, which may be due to ISR fluctuations. |
NotEnoughReplicasAfterAppendException | After data is written locally to the Broker, ISR fluctuations may cause the min.insync.replicas requirement to not be met. | - |
BrokerNotAvailableError | Leader not found for the partition. | Since the client caches the Topic's Metadata, when the Leader switchover of a Partition occurs, production or consumption requests may still be sent to the old Leader. In this case, this error will be returned to the client. The client will auto-update the Metadata info. After the switch, new production requests sent to the old Leader should automatically adjust to the new Leader after reporting errors, theoretically without affecting the integrity of data write and consumption. |
NotLeaderForPartitionError | Leader not found for the partition. | Since the client caches the Topic's Metadata, when the Leader switchover of a Partition occurs, production or consumption requests may still be sent to the old Leader. In this case, this error will be returned to the client, and the client will auto-update the Metadata info. After the switch, new production requests sent to the old Leader should automatically adjust to the new Leader after reporting errors, theoretically without affecting the integrity of data write and consumption. |
Logging Configuration at DEBUG Level Exception
The following exception may appear when logging configuration is at DEBUG level, and the client will handle it automatically.
Abnormal | Description | Analysis and Description |
OffsetOutOfRangeException | The Offset passed in by the consumer when pulling messages exceeds the limit. | If the client sets the Offset reset policy (earliest or latest), the client will reset the Offset based on policies. Otherwise, the user program is required to fix this exception. |
GroupLoadInProgressException | The corresponding Coordinator for the ConsumerGroup is loading. | The server side may briefly appear during upgrade, and the client will retry automatically. |
GroupCoordinatorNotAvailableException | The Coordinator is unavailable. | The server side may briefly appear during upgrade, and the client will retry automatically. |
NotCoordinatorForGroupException | The current node is not the Coordinator of this ConsumerGroup. The Coordinator has migrated to another node. | The server side may briefly appear during upgrade, and the client will retry automatically. |
IllegalGenerationException | The ConsumerGroup generation is invalid. | Heartbeat timeout may occur or new consumers may join. The consumer will automatically retry joining the ConsumerGroup. |
RebalanceInProgressException | ConsumerGroup rebalance is currently in progress. | Heartbeat timeout may occur or new consumers may join. The consumer will automatically retry joining the ConsumerGroup. |
フィードバック