Operate and Debug
View as MarkdownDex Web and dexcli read Flows through the same Dex Server API as your Workers. Dex Web shows a run in application terms. dexcli prints the same data as JSON, for scripts and incident records.
Find and read a Flow
In Dex Web, Search and Summary find Flows and show their state. A run's page shows its active Steps, Attributes, and Channels. Its Timeline lists each event of the run, with its inputs, outputs, and Attribute changes.
From a terminal, read the same run with its Flow ID and Run ID. These commands only read, and they print JSON:
dexcli flow inspect FLOW_ID --run-id RUN_ID
dexcli flow history FLOW_ID --run-id RUN_ID --all
dexcli flow inspect returns the current summary and state. dexcli flow history returns the run's events. The CLI reference lists every command.
A Flow is stuck
A Flow advances only when a Worker takes its next Step. When a Step stays active or its retry count grows, check the Worker first:
- Collect the Flow ID, Run ID, Flow type, Worker version, and Dex Server address.
- Read the Worker logs for handler exceptions, registration failures, and startup configuration.
- Check that the Worker's outbound streams to Dex Server are connected, with the right address, TLS, and credentials.
- Check that the deployed Worker registers the Flow, Step, and RPC names that the open Flow uses.
- Open the Step in Dex Web. Its attempt, Worker error, gRPC status, and stack trace tell an unavailable Worker from an application failure.
After you fix the Worker, an active retry continues on its own. Do not restart or time travel a Flow only to test connectivity.
A Flow failed
A Flow fails when a Step handler fails and its retries run out, or when its Flow timeout is set to fail it. A Flow timeout can also cancel the Flow or run a handler. By default, Step retries stop after 4 hours. In Dex Web, select the failed event in Timeline. Its Failure panel shows the attempt, the error, and the gRPC status. Expand Stack trace before you hand the failure to the team that owns the code.
Troubleshoot a Flow run has the full read-only workflow, with screenshots.
Recover a Flow with Time Travel
Time Travel moves a run back to an earlier point and runs it again from there. Use it after you deploy a fix. Verify the fix with a new run first.
Every Step after that point runs again, with its external calls, so each call needs an idempotency key. Input that came from outside the run after that point, such as RPC calls, is applied again by default. Start Time Travel from Dex Web, a Client, or dexcli flow time-travel; the CLI reference lists its flags. Recover a Flow with Time Travel gives the options.
What runs again after a crash
Dex saves each finished Step, so a crash repeats only the work that was in progress.
| Event | What runs again |
|---|---|
| A Worker crashes or stops | The Step attempts it was running |
| A Dex Server node fails over | Every attempt that a Worker had received |
| You deploy new Step code | Nothing that already finished |
| You run Time Travel | Every Step after the chosen point |
Failover and Deploys covers each event, including ASYNC Steps.
Next
- Deploy Code Changes: change Flow code while runs are still open.
- Troubleshoot a Flow run: the full debugging workflow.