Replay debugger
fluidgrids replay tells you whether a run's history still replays against your code. The replay debugger tells you where and why it does not: it walks the history event by event, maps each step to a line of your TypeScript, and can stop in a debugger at the first mismatch.
Trace a replay
fluidgrids replay <runId> --trace
fluidgrids replay histories/order-7.history.json --trace --json
The trace lists every event in the history with the command that produced it, the source location of the call, and whether the replay matched it, found a mismatch, or issued a new command that the history does not have. With --json the trace is printed as one JSON object, for scripts and editors.
Break on the first mismatch
fluidgrids replay <runId> --break-on-mismatch
fluidgrids replay <runId> --break-on-mismatch --inspect=127.0.0.1:9229
--break-on-mismatch stops at the first divergence and reports what the history recorded, what the code did instead, and the source line. With --inspect, the CLI starts under the Node.js inspector and pauses there, so you can attach VS Code or Chrome DevTools, look at local variables and step through your own TypeScript with source maps.
Debug the code the run actually ran
Your working copy may not be the code a run was started with. --remote-code downloads the exact source archive of the run's version and rebuilds it:
fluidgrids replay <runId> --remote-code --trace
- The archive is fetched through a short-lived download link (valid for at most 15 minutes) and needs read access to the workflow.
- The rebuilt bundle must have the same build id as the one the run used. If it does not, the debugger refuses to continue rather than debug different code. Use the same
@fluidgrids/workflowsversion as the run (shown byfluidgrids runs describe). - Debugging runs on your machine only. It never changes the run or its history.
The stored code runs on your machine
The replay runs the stored code on your machine in a Node.js vm, and a vm is not a sandbox: the code can reach your process, your files and any credentials in your environment. Any member of the workspace may have pushed the version you replay, so only debug code from people you trust.
Before it downloads anything, --remote-code prints that warning and asks:
Run the stored code of order-flow v3 on this machine? [y/N]
Anything but y or yes stops the command, and nothing is downloaded or run. Scripts and CI, which have no terminal to answer on, must pass --yes once they trust the code:
fluidgrids replay <runId> --remote-code --trace --yes --json
With --json (or --output json) the CLI never prompts: without --yes it refuses, and in both cases the envelope carries the warning as a debug.untrustedCode diagnostic, so a script cannot miss it. With --inspect, the CLI asks before it starts the debugger.
If you build your own tooling on @fluidgrids/workflows/debug, traceReplay refuses to run unless you pass trustedCode: true. Never call it on tenant code inside a service or worker; the managed workers replay in an isolated QuickJS runtime instead.
In VS Code
The FluidGrids VS Code extension (0.2.0 or later) adds Replay run (the trace as a tree, with the mismatch marked in the editor) and Debug replay (a debug session that stops at the mismatch) to every durable run. From extension 0.2.1, when you replay against the run's exact code, the extension asks you to confirm in a dialog first.