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

Step 2a: Replay with the Same Input

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[].

Step 2b: Replay with New Input

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"

Step 3: Watch the New Run

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:

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

Common Replay Workflow

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

1. Trigger a run and it fails
2. Read the logs/events to understand why
3. Fix the code (the worker auto-reloads if reload: true in hatchet.yaml)
4. Replay the run with hatchet runs replay RUN_ID -o json -p HATCHET_PROFILE
5. If it fails again, repeat from step 2