In AWS Step Functions, what JSON does a Catch block pass to the target state, and what changes if the catcher sets ResultPath to "$.error"?

## What the catcher actually produces When an error escapes retrying and a catcher in the `Catch` array matches it, Step Functions does not simply jump to another state — it *produces a result* for the failed state and then transitions. That result is always the same shape: ```json { "Error": "InventoryUnavailable", "Cause": "{\"errorMessage\":\"sku 88213 out of stock\", ...}" } ``` `Error` is the error name that matched. `Cause` is a **string**, not an object. For a Lambda-backed task it holds the serialised function error — message, type, and usually a stack trace — which means a downstream state that wants a field out of it has to parse the string, not path into it. Designing your workflow to branch on `Error` rather than to inspect `Cause` is the more robust choice, and it is why raising typed, named errors is worth the effort. ## ResultPath decides what the next state sees `ResultPath` is the ordinary Amazon States Language field that says *where a state's result is placed relative to that state's input*. It behaves the same way on a catcher as anywhere else, and the three cases are: - **`"$"` (the default)** — the result replaces the input. The `Next` state receives only `{ "Error": ..., "Cause": ... }`. - **A path such as `"$.error"`** — the result is inserted into a copy of the input at that key. The `Next` state receives the original input *plus* an `error` field. - **`null`** — the result is discarded and the input passes through untouched. The `Next` state sees the original input and nothing about the failure. The default is the trap. It is easy to write a catcher that routes to `CompensateOrder`, and only discover in production that `CompensateOrder` has no idea which order to compensate, because the input it needed was overwritten by an error blob. The symptom is a recovery branch that fails on a missing field — a failure inside your failure handling, which is a bad place to be. ## What good looks like ```json "Catch": [ { "ErrorEquals": ["States.ALL"], "ResultPath": "$.error", "Next": "CompensateOrder" } ] ``` With the state's input being `{"orderId": "A-77", "items": 3}`, `CompensateOrder` now receives: ```json { "orderId": "A-77", "items": 3, "error": { "Error": "InventoryUnavailable", "Cause": "..." } } ``` It can release the hold on order `A-77` *and* record the reason. If instead you genuinely want the recovery branch to behave as though the failure carried no extra information — for example, it just retries a different path with the same payload — `"ResultPath": null` is the honest expression of that. ## Two related details worth knowing First, a path that cannot be applied to the input is a runtime failure, not a silent no-op: Step Functions raises `States.ResultPathMatchFailure`. Since this happens *inside* your error handling, it is worth keeping the path simple — a single top-level key such as `$.error` — rather than something that assumes a nested structure exists. Second, nesting the error grows the payload rather than replacing it. Every state's input and output is bounded by a payload quota, and a large `Cause` — a long stack trace, for example — accumulating alongside a big business payload can push a state over that boundary and raise `States.DataLimitExceeded`. On workflows carrying substantial data, catching to a state that immediately trims the payload down to identifiers is the defensive move. ## Why this question separates people Anyone who has drawn a state machine on a whiteboard knows a catcher routes to another state. Only someone who has *shipped* one knows the target state's input silently changes shape when it does. It is a small piece of ASL semantics with an outsized effect on whether the failure path actually works when it is finally exercised — which, by definition, is the worst possible moment to find out that it does not.