Skip to main content

The Terminate Node & Error Branches

Not every run succeeds. When your workflow hits an error it can't recover from, it should tell the platform — otherwise the execution sits in running forever, waiting for a callback that never comes. The Terminate node is how you report that failure cleanly.

What Terminate does​

The Terminate node calls the platform to mark the execution failed, with an optional reason string (static text or an expression, e.g. the error from a prior node). The platform records it, writes a final log entry, and — because a workflow-reported failure is treated as external rather than a platform fault — marks the execution failed_transient, which means it's retryable. The external_execution_id is included automatically from the shared context; you just supply the reason.

Where it goes: error branches only​

This is the placement rule that matters most:

  • Terminate is the last node of an error branch — the path your workflow takes when a step fails and can't continue. That's its only home.
  • It is not the last node of the happy path. A successful run ends with the Complete node, not Terminate.
  • Never put a Terminate after a Complete. The run is already finished once Complete fires; a trailing Terminate is redundant at best and harmful at worst.

Getting this wrong is the classic beginner mistake — dropping a Terminate at the very end of everything, or after Complete. Keep the two ends of your workflow distinct: Complete closes success, Terminate closes failure.

Don't stack it with self-terminating nodes​

One more rule: don't combine Terminate with nodes that already self-terminate. The Agent and Log nodes end the run themselves on an error or a limit breach — so putting a Terminate right after one is either unreachable or a double-termination. Use Terminate for the failures you catch and route down an error branch (a service call that came back bad, a validation you did yourself), not for the ones the Circus nodes already handle.

The bigger picture: nothing hangs​

Between the self-terminating Agent and Log nodes, your explicit Terminate on error branches, and the platform's reconciler as a final backstop, a Circus workflow is designed so that no run is ever left stuck in running. Your part is simple: end each error branch with a Terminate so the platform learns about the failures you handle — and let the nodes and the reconciler cover the rest.