Skip to content

KAFKA-19283: Update transaction exception handling documentation #19931

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 10, 2025

Conversation

k-raina
Copy link
Contributor

@k-raina k-raina commented Jun 9, 2025

Added docs on Enhancements to transactional producer error handling:

  • Added standardized exception categories (RetriableException,
    RefreshRetriableException, AbortableException,
    ApplicationRecoverableException, InvalidConfigurationException,
    KafkaException) to ensure clearer error handling patterns.
  • Included a link to example template code for handling transaction
    exceptions: Transaction Client
    Demo
    .

Reviewers: Justine Olshan jolshan@confluent.io

@github-actions github-actions bot added triage PRs from the community docs small Small PRs labels Jun 9, 2025
docs/design.html Outdated
@@ -340,6 +340,18 @@ <h3 class="anchor-heading"><a id="usingtransactions" class="anchor-link"></a><a
transactions. However, in the event of a transaction abort, the application's state and in particular the current position of the consumer must be reset explicitly so that it can
reprocess the records processed by the aborted transaction.
<p>
The error handling for transactional producer has been standardized which ensures consistent behavior and clearer error handling patterns. The exception categories are now more precisely defined:
<ol>
<li><strong>RetriableException</strong>: Temporary exceptions that are retried automatically by the client. These are handled internally and don't require application intervention.</li>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

one nit: can we share which exceptions bubble up to the application and which don't?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed feedback in commit 638a212

@k-raina k-raina requested a review from jolshan June 9, 2025 16:46
docs/design.html Outdated
<li><strong>RefreshRetriableException</strong>: Exceptions requiring metadata refresh before retry. These are handled internally by the client after refreshing metadata and don't bubble up to the application.</li>
<li><strong>AbortableException</strong>: Exceptions that require transaction abort and reprocessing. These bubble up to the application, which must handle them by aborting the transaction and resetting the consumer position.</li>
<li><strong>ApplicationRecoverableException</strong>: Exceptions that bubble up to the application and require application handling. The application must implement its own recovery strategy, which must include restarting the producer.</li>
<li><strong>InvalidConfigurationException</strong>: Configuration-related exceptions that bubble up to the application and require application handling and producer restart.</li>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

did we decide that these require producer restart still?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Corrected in commit 083bccc

Producer doesn't necessary need to restart, as it might be fixed by simple retry.

@k-raina k-raina requested a review from jolshan June 9, 2025 18:06
@jolshan jolshan added ci-approved and removed triage PRs from the community labels Jun 9, 2025
Copy link
Member

@jolshan jolshan left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

@jolshan jolshan merged commit dbfda79 into apache:trunk Jun 10, 2025
25 checks passed
@mimaison
Copy link
Member

Can we now close https://issues.apache.org/jira/browse/KAFKA-19283 and https://issues.apache.org/jira/browse/KAFKA-16906?
And mark KIP-1050 as complete?

@mimaison
Copy link
Member

ping @jolshan

@k-raina
Copy link
Contributor Author

k-raina commented Jun 16, 2025

@mimaison Sorry missed your ping on PR.
I have closed respective JIRAs and updated KIP-1050 status to complete

k-raina added a commit to k-raina/kafka that referenced this pull request Jun 17, 2025
…che#19931)

Added docs on Enhancements to transactional producer error handling:

* Added standardized exception categories (`RetriableException`,
`RefreshRetriableException`, `AbortableException`,
`ApplicationRecoverableException`, `InvalidConfigurationException`,
`KafkaException`) to ensure clearer error handling patterns.
* Included a link to example template code for handling transaction
exceptions: [Transaction Client

Demo](https://github.com/apache/kafka/blob/trunk/examples/src/main/java/kafka/examples/TransactionalClientDemo.java).

Reviewers: Justine Olshan <jolshan@confluent.io>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants