TypeScript SDK v4 is now available! See what's new
GuidesCLI

Debug a function run from your terminal

This guide walks you through finding a failed run, pulling its trace, and identifying which step broke. You do this entirely from the terminal using the Inngest CLI.

Prerequisites

  • Inngest CLI: npx inngest-cli@latest
  • An API key set as INNGEST_API_KEY (create one in the Inngest dashboard under Settings > API Keys)

1. Get the run summary

You have a run ID from a log, alert, or the dashboard. Fetch the summary:

npx inngest-cli@latest api --prod get-function-run 01KTCTWT8XDEGWDMVX3Q9M69ND

The response shows the run's status, function, timing, and trigger:

{
  "data": {
    "id": "01KTCTWT8XDEGWDMVX3Q9M69ND",
    "status": "FAILED",
    "function": {
      "name": "process-order",
      "slug": "my-app-process-order"
    },
    "queuedAt": "2026-06-05T21:26:44.765Z",
    "endedAt": "2026-06-05T21:26:45.954Z",
    "durationMs": "1096"
  }
}

The run failed. Pull the trace to see which step broke.

2. Fetch the trace

The trace shows every step in the run with its status, timing, and output:

npx inngest-cli@latest api --prod get-function-trace 01KTCTWT8XDEGWDMVX3Q9M69ND --include-output

The response is a tree of spans. Each span is a step. Look for the one with a failed status:

{
  "data": {
    "runId": "01KTCTWT8XDEGWDMVX3Q9M69ND",
    "rootSpan": {
      "name": "process-order",
      "status": "FAILED",
      "children": [
        {
          "name": "validate-input",
          "status": "COMPLETED",
          "stepOp": "RUN",
          "durationMs": "12"
        },
        {
          "name": "charge-card",
          "status": "COMPLETED",
          "stepOp": "RUN",
          "durationMs": "340"
        },
        {
          "name": "create-shipment",
          "status": "FAILED",
          "stepOp": "RUN",
          "durationMs": "744",
          "output": {
            "error": "shipping API returned 503"
          }
        }
      ]
    }
  }
}

The create-shipment step failed with a 503 from the shipping API. The validate-input and charge-card steps completed. You know exactly where it broke and what the error was.

3. Pipe to jq for quick filtering

Extract just the failed steps:

npx inngest-cli@latest api --prod get-function-trace 01KTCTWT8XDEGWDMVX3Q9M69ND --include-output \
  | jq '[.data.rootSpan.children[] | select(.status == "FAILED")]'

4. Test a fix locally

Once you identify the issue, fix the code and test against your local dev server. The CLI targets the dev server by default:

# Invoke the function locally
npx inngest-cli@latest api invoke-function my-app process-order \
  --data '{"orderId": "test-123", "address": "123 Main St"}'

# Check the run
npx inngest-cli@latest api get-event-runs <event_id> --include-output

No --prod flag means it hits http://localhost:8288. The dev server must be running.

Next steps