Add Java SDK error-handling best practices page

[Duncanma]

What does this PR do?

Adds docs/develop/java/best-practices/error-handling.mdx — Java was the one major SDK missing the error-handling page that Go, Python, .NET, and Ruby already have.

Closes #5013
Closes #4006

The page covers:

• Catching Exception, never Throwable or Error — with the reasoning (DestroyWorkflowThreadError, UnsupportedVersion) and a catch-decision order for Workflow/Update/Signal code
• The catch (Throwable t) swallow-all anti-pattern, spelled out with the three concrete failure modes it causes
• Wrapping checked exceptions with Workflow.wrap() / Activity.wrap() instead of adding them to method signatures, including direct answers to "do I need to wrap what I throw" and "do I need to re-wrap after unwrapping"
• Reading a failure's cause chain (ActivityFailure → ChildWorkflowFailure → ApplicationFailure), including the getMessage() vs getOriginalMessage() gotcha and matching on getType() instead of instanceof
• Handling Activity/Child Workflow failures and cancellation, linking out to the existing Non-Retryable Errors and Saga Pattern design-pattern pages rather than duplicating them
• Centralizing failure conversion in a WorkerInterceptor

Also wires the page into sidebars.js and the best-practices index, and cross-links it from the cancellation page (the one spot #5013 called out as having an indirect, one-sentence mention of the catch-Throwable rule today).

Notes to reviewers

Every code-level claim is verified against sdk-java source (CheckedExceptionWrapper, the failure/* classes, DestroyWorkflowThreadError, UnsupportedVersion), the official HelloException and bookingsaga samples, and an internal best-practices writeup on Java error handling — not just the community forum post cited in #5013.

Scope note: the source material I checked goes considerably deeper (retry classification by HTTP/gRPC status code, cross-attempt error-context accumulation via heartbeats, a generic exception↔ApplicationFailure converter pattern, full Saga mechanics). I kept those out of this page to match the depth of the sibling Go/.NET/Ruby pages and avoid duplicating /design-patterns/non-retryable-errors and /design-patterns/saga-pattern — happy to split any of that into follow-up pages if you'd rather have it documented too.

┆Attachments: EDU-6902 Add Java SDK error-handling best practices page

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
temporal-documentation	Ready	Preview	Aug 7, 2026 9:51pm

[github-actions]

📖 Docs PR preview links

• Develop
  • Java
    • Best Practices
      • Best practices
      • Error handling
    • Workflows
      • Interrupt a Workflow