Temporal is a durable execution platform, and most mistakes with it come from misreading one word of that phrase. It does not make your side effects happen once; it makes your process finish. It does not run your code; it records what your code decided and hands work to Workers you deploy. And that deciding code is re-executed against a recorded log, which is why reading the clock inside it is a bug. Get those three straight and the rest is detail.
Each chapter opens with the short version. Tap one to read the detail.
What durable execution promises, and where your code actually runs
~2 min
The guarantee is narrower than it sounds: your process runs to completion despite crashes, not that any side effect happened once. The other half people get backwards — the Service never runs your code. A Worker you deploy holds every line.
Definition, Execution, and the identifier that makes starting safe
~2 min
A Definition is code; each run is an Execution with its own history. The identifier is where people waste the platform: give it a random value and you discard its only duplicate protection — at most one Execution with a given Workflow Id is open at a time.
History is the state — and it has a ceiling
~2 min
Nothing snapshots your Workflow's memory. State is rebuilt by re-running the code against a recorded event log, which is why a completed Activity is never executed again — its stored result is handed back. That log is capped, and the cap is why child Workflows and Continue-As-New exist.
The constraint everything else rests on
~2 min
Determinism here is not "avoid random numbers". Replay compares the Commands your code emits against the Events already recorded, so anything that adds, removes, or reorders a Command breaks the run — including a reasonable-looking change shipped while it was mid-flight.
Activities: the only place the outside world gets in
~2 min
An Activity is an ordinary function doing one well-defined thing, and it may run more than once. A failed attempt restarts from the initial state rather than where it stopped, so idempotency is a requirement, not a preference. Heartbeat details are what change that.
Which timeout to set, and what retries already do for you
~2 min
Activities retry indefinitely by default with exponential backoff, so a permanent failure presents as a hang rather than an error. Of the four timeouts, usually only Start-To-Close is yours to set; reaching for the queue-time one protects nothing, because it is non-retryable by design.
Failed, stuck, or unwinding
~2 min
The distinction that costs the most debugging time: an unexpected exception in Workflow code does not fail the Workflow. It fails the Workflow Task, which retries until the Execution Timeout — unlimited by default — so the run is stuck rather than dead, and shipping a fix resumes it.
What wakes a waiting Workflow
~3 min
A Workflow spends most of its life waiting, and only three things end a wait: a timer fires, a message arrives, or a Schedule starts a new run. Waiting is nearly free — Workers hold no resources during a timer — but each carries a default that quietly surprises people.
Workers pull work, and four numbers say what to change
~2 min
Nothing is ever pushed to a Worker. Workers long-poll a Task Queue, which is why they need no inbound ports and no service discovery. It also means capacity problems and code problems surface in different metrics, and confusing them sends you tuning what was never wrong.
Changing code that is already running
~2 min
Deploying a new Definition replays old histories against new code, so an edit that looks harmless can break runs that started last week. A patch marks a branch so existing runs keep the old path. The only real proof is replaying actual histories against it.
Everything you pass is persisted — and who can read it
~2 min
Inputs, results, and message arguments are all serialized into history, so a Workflow argument is a durable, inspectable record rather than a function parameter. Two consequences: payloads are capped at 2 megabytes per request, and you can search only what you deliberately indexed.
Written by Keentune. We are not affiliated with or endorsed by the organizations whose documentation informs this guide, and any linked sources belong to their respective owners.
All exam, test, and product names and trademarks are the property of their respective owners and are used here for identification and reference only. Keentune is independent study practice — not affiliated with, authorized, or endorsed by any of these organizations.