Exceptions

typedkafka.exceptions.KafkaErrorContext dataclass

Structured context for Kafka errors.

Provides machine-readable metadata about the Kafka operation that failed, making it easier to log, route, or retry errors programmatically.

Attributes:

Name	Type	Description
topic	Optional[str]	The topic involved in the failed operation
partition	Optional[int]	The partition number
offset	Optional[int]	The message offset
key	Optional[bytes]	The message key
timestamp	Optional[int]	The message timestamp
headers	dict[str, bytes]	Message headers as a dict

typedkafka.exceptions.KafkaError

Bases: Exception

Base exception for all Kafka-related errors.

All typedkafka exceptions inherit from this base class, making it easy to catch all Kafka-related errors with a single except clause.

Attributes:

Name	Type	Description
context		Structured error context with topic/partition/offset metadata
original_error		The underlying error that caused this exception

Examples:

>>> try:
...     producer.send("topic", "message")
... except KafkaError as e:
...     logger.error(f"Kafka operation failed: {e}")
...     if e.context.topic:
...         logger.error(f"Topic: {e.context.topic}")

__init__(message, context=None, original_error=None)

Initialize a KafkaError.

Parameters:

Name	Type	Description	Default
message	str	Human-readable error description	required
context	Optional[KafkaErrorContext]	Structured context about the failed operation	None
original_error	Optional[Exception]	The underlying exception that caused this error	None

typedkafka.exceptions.ProducerError

Bases: KafkaError

Raised when a Producer operation fails.

This exception is raised when message production fails, such as: - Message serialization errors - Network connectivity issues - Broker unavailability - Invalid topic names - Queue full errors

Attributes:

Name	Type	Description
message		Human-readable error description
original_error		The underlying error from confluent-kafka (if any)
context		Structured error context

Examples:

>>> try:
...     producer.send("invalid-topic!", {"key": "value"})
... except ProducerError as e:
...     logger.error(f"Failed to produce message: {e}")

__init__(message, context=None, original_error=None)

Initialize a ProducerError.

Parameters:

Name	Type	Description	Default
message	str	Human-readable error description	required
context	Optional[KafkaErrorContext]	Structured error context	None
original_error	Optional[Exception]	The underlying exception that caused this error	None

typedkafka.exceptions.ConsumerError

Bases: KafkaError

Raised when a Consumer operation fails.

This exception is raised when message consumption fails, such as: - Message deserialization errors - Consumer group coordination failures - Offset commit errors - Network connectivity issues

Attributes:

Name	Type	Description
message		Human-readable error description
original_error		The underlying error from confluent-kafka (if any)
context		Structured error context

Examples:

>>> try:
...     for message in consumer:
...         process(message)
... except ConsumerError as e:
...     logger.error(f"Consumer error: {e}")

__init__(message, context=None, original_error=None)

Initialize a ConsumerError.

Parameters:

Name	Type	Description	Default
message	str	Human-readable error description	required
context	Optional[KafkaErrorContext]	Structured error context	None
original_error	Optional[Exception]	The underlying exception that caused this error	None

typedkafka.exceptions.SerializationError

Bases: KafkaError

Raised when message serialization or deserialization fails.

This occurs when: - JSON encoding/decoding fails - Avro schema validation fails - Custom serializer raises an exception - Message format is invalid

Attributes:

Name	Type	Description
message		Human-readable error description
value		The value that failed to serialize/deserialize
original_error		The underlying error (if any)

Examples:

>>> try:
...     producer.send_json("topic", non_serializable_object)
... except SerializationError as e:
...     logger.error(f"Failed to serialize message: {e}")

__init__(message, value=None, context=None, original_error=None)

Initialize a SerializationError.

Parameters:

Name	Type	Description	Default
message	str	Human-readable error description	required
value	Any	The value that failed to serialize/deserialize	None
context	Optional[KafkaErrorContext]	Structured error context	None
original_error	Optional[Exception]	The underlying exception that caused this error	None

typedkafka.exceptions.ConfigurationError

Bases: KafkaError

Raised when Kafka configuration is invalid.

This occurs when: - Required configuration fields are missing - Configuration values are mutually inconsistent - Validation of the configuration dictionary fails

Examples:

>>> try:
...     config = ProducerConfig().build(validate=True)
... except ConfigurationError as e:
...     logger.error(f"Invalid config: {e}")

typedkafka.exceptions.TransactionError

Bases: KafkaError

Raised when a transaction operation fails.

This occurs when: - Transaction initialization fails - Commit or abort fails - The transactional producer enters a fatal state

Examples:

>>> try:
...     with producer.transaction():
...         producer.send("topic", b"msg")
... except TransactionError as e:
...     logger.error(f"Transaction failed: {e}")