Replay a Hatchet Run

These are instructions for an AI agent to replay a previously executed Hatchet run, optionally with modified input. Follow each step in order.

Step 1: Inspect the Original Run

First, understand what happened in the original run:

hatchet runs get RUN_ID -o json -p HATCHET_PROFILE

From the response, note:

.run.displayName — the workflow name (needed if re-triggering with new input)
.run.input — the original input JSON
.run.status — why you might be replaying (e.g. FAILED)
.tasks[].status and .tasks[].errorMessage — which specific tasks failed and why

If you want to re-run the exact same workflow with the same input (e.g. after fixing a bug in the task code):

hatchet runs replay RUN_ID -o json -p HATCHET_PROFILE

This creates a new run of the same workflow with the same input. The response includes the new run IDs in .ids[].

If you need to change the input (e.g. fixing bad input data), you must trigger a new run instead of using replay:

Write the new input JSON to a uniquely-named temp file:

HATCHET_INPUT_FILE="/tmp/hatchet-input-$(date +%s)-$$.json"
cat > "$HATCHET_INPUT_FILE" << 'ENDJSON'
NEW_INPUT_JSON
ENDJSON

Then trigger a fresh run using the workflow name from Step 1:

RUN_ID=$(hatchet trigger manual -w WORKFLOW_NAME -j "$HATCHET_INPUT_FILE" -p HATCHET_PROFILE -o json | jq -r '.runId')

Clean up the temp file:

rm -f "$HATCHET_INPUT_FILE"

After either Step 2a or 2b, you have a new run ID. Poll for completion:

hatchet runs get <NEW_RUN_ID> -o json -p HATCHET_PROFILE

Check .run.status and .tasks[].status every 5 seconds until all reach a terminal state (COMPLETED, FAILED, CANCELLED).

If the new run also fails, use the debug instructions:

hatchet runs logs <NEW_RUN_ID> -p HATCHET_PROFILE for application logs
hatchet runs events <NEW_RUN_ID> -o json -p HATCHET_PROFILE for lifecycle events

The typical flow when an agent is iterating on task code: