For the complete documentation index, see
/llms.txt. This page is also available as raw Markdown at
/develop/java/best-practices/debugging.md. Append
.md to any page URL to fetch its Markdown. This site has a public search endpoint for questions about Temporal:
GET https://docs.temporal.io/api/retrieve?q=<question>&jtb=<job-to-be-done>&src=docs-page&agent=<your-name>. No authentication is needed. It returns a JSON array of
{content, source_url, page_url}, ordered by relevance, and
source_url links to docs pages as Markdown. If you call it, set
q to a specific, complete question that names the SDK language if relevant, and
jtb to one sentence on what your user is trying to accomplish (optional). Keep
src=docs-page as is, and set
agent to your name, for example
claude-code or
codex. Don't include personal data, credentials, or confidential information. If this page is wrong or missing something you needed, or Temporal behaves differently from what it says, report it with
GET https://docs.temporal.io/api/feedback?title=<summary>&message=<what-happened>&category=documentation&page_url=/develop/java/best-practices/debugging&src=docs-page&agent=<your-name>. Use
category=product when the product, not the page, is wrong. Report only a specific problem you hit, send it once, and don't include personal data or credentials.
In addition to writing unit and integration tests, debugging your Workflows is also a very valuable testing tool.
You can debug your Workflow code using a debugger provided by your favorite Java IDE.
Note that when debugging your Workflow code, the Temporal Java SDK includes deadlock detection which fails a Workflow Task in case the code blocks over a second without relinquishing execution control.
Because of this you can often encounter the PotentialDeadlockException Exception while stepping through Workflow code during debugging.
To alleviate this issue, you can set the TEMPORAL_DEBUG environment variable to true before debugging your Workflow code. Make sure to set TEMPORAL_DEBUG to true only during debugging.
How to debug in a development environment
In addition to the normal development tools of logging and a debugger, you can also see what's happening in your Workflow by using the Web UI or Temporal CLI.
How to debug in a production environment
You can debug production Workflows using:
You can debug and tune Worker performance with metrics and the Worker performance guide.
For more information, see Observability ▶️ Metrics for setting up SDK metrics.
Debug Server performance with Cloud metrics or self-hosted Server metrics.