What is OrchestratorBlockedException? #242
Description
Creating a pinned issue to help folks who may have questions on this topic which occasionally comes up. This information is available in the JavaDocs, but sometimes gets missed, so I'm putting more context in a GitHub issue in hopes that this may be more discoverable. At some point this will be added to a Java-specific developer guide for Durable Task Java SDK.
What is OrchestratorBlockedException
OrchestratorBlockedException is a subclass of RuntimeException that is thrown when an orchestrator calls Task.await() on a task that isn’t yet completed.
The reason for this exception isn't that something went wrong in the code execution. Rather, it's part of the mechanism of how orchestrator functions get suspended (“yielded”) so the framework can checkpoint state, schedule further work (like activities or timers), and unload the orchestrator from memory until the next event. In effect, it’s used to block/suspend the orchestrator’s execution until the awaited task finishes.
It is a control-flow exception. This exception must never be caught by user code, and the exception message emphasizes this. If you catch it, you may prevent the orchestration from saving its state or scheduling new work, which can lead to the orchestration “getting stuck.”
Why it is thrown
In an orchestrator function in Java, when you call something like ctx.callActivity(“Foo”, input, SomeClass.class).await(), that returns a Task<SomeClass>. If that task is not completed yet, .await() needs to pause the orchestrator until that task finishes. This is similar to how coroutines work, particularly in languages that support async/await (which Java does not).
The mechanism Durable Task uses to implement the coroutine pattern is to throw (under the covers) an OrchestratorBlockedException. The orchestration runtime catches that internally, records the current workflow state (all scheduled but not yet completed tasks, etc.), checkpoints, and exits the function invocation (as a success). Later, when the awaited task (activity / timer / external event) completes, the orchestrator is resumed (replayed) from that point.
In summary: OrchestratorBlockedException is not an error. It’s an expected behavior in orchestrator functions to implement durable coroutines.