In AWS Step Functions, what does the error name States.ALL match inside a Retry or Catch ErrorEquals array, and where is it allowed to appear?
answer
- the wildcard error name
- exact string match, no globs
- order decides which handler wins
- must stand alone, and last
- one error it still cannot catch
basics
~20 sStates.ALL is the Step Functions wildcard error name that matches nearly every error a state can raise. It must be the only entry in its ErrorEquals array and must sit in the final retrier or catcher, because they are evaluated top to bottom.
solid answer
~40 sEvery failure in a state machine surfaces as a short error name plus a free-form `Cause`. Some names come from the invoked service or function; Step Functions reserves the `States.` prefix for its own, such as `States.TaskFailed`, `States.Timeout`, `States.HeartbeatTimeout`, `States.Permissions`, `States.NoChoiceMatched` and `States.DataLimitExceeded`. `States.ALL` is the catch-all: it matches any error the state raises, with one documented exception — `States.Runtime`, which is never retriable and is not caught by `States.ALL`. Two placement rules are enforced when the definition is validated: `States.ALL` must be the only string in its `ErrorEquals` array, and it must be in the last retrier of a `Retry` array or the last catcher of a `Catch` array. Retriers and catchers are matched in order and the first match wins, so specific names go first and `States.ALL` is the backstop.
go deeper
Know that failures carry an error name plus a Cause, that States.ALL is the wildcard, and that it goes last and alone in the array. Being able to name three or four States.* errors is enough at this level.
Explain that retriers and catchers are scanned in array order and the first match wins, so a wildcard placed early would make everything after it dead code — which is why the definition is rejected outright rather than misbehaving at runtime.
Show that you design the name list deliberately: specific transient service errors first with their own settings, domain errors routed to their own branch, and a wildcard backstop that records the failure. Mention States.Runtime as the gap.
Own the convention across teams: which failures are allowed to be named in a workflow at all, whether domain errors come from typed exceptions or Fail states, and how error names stay stable enough that routing logic does not break when a function is rewritten.
## What an error name is When a state in an AWS Step Functions state machine fails, the failure is expressed as a small JSON object with two fields: `Error`, a short string called the **error name**, and `Cause`, a free-form human-readable string. Everything in the error-handling system — retriers, catchers, and the `Fail` state — keys off that error name. Error names come from two sources. The first is the thing the `Task` state invoked: if a Lambda function throws a typed exception, its type becomes the error name; if an AWS SDK integration fails, the service's exception name becomes the error name. The second is Step Functions itself, which reserves the `States.` prefix for the errors it generates. ## The predefined States.* names The ones worth being able to recite: - `States.ALL` — the wildcard, described below. - `States.TaskFailed` — a `Task` state's underlying work reported a failure. - `States.Timeout` — the task exceeded `TimeoutSeconds`. - `States.HeartbeatTimeout` — no heartbeat arrived within `HeartbeatSeconds`. - `States.Permissions` — the execution role lacked permission to make the call. - `States.DataLimitExceeded` — a state's input or output exceeded the payload quota. - `States.NoChoiceMatched` — a `Choice` state matched nothing and had no `Default`. - `States.BranchFailed` — a branch inside a `Parallel` state failed. - `States.Runtime` — an internal runtime failure, described below. Matching is exact string equality. `ErrorEquals` accepts no prefixes, no globs and no regular expressions, so `Lambda.*` is not a thing; you list the names you mean. ## What States.ALL actually does `States.ALL` matches any error name the state produces, custom names included. Two structural rules apply and are checked when you create or update the state machine, not silently at runtime: 1. It must be the **only** element of its `ErrorEquals` array. `["States.ALL", "States.Timeout"]` is rejected. 2. It must appear in the **last** retrier of a `Retry` array, or the last catcher of a `Catch` array. Anything after it is unreachable, so the definition is invalid. Both rules exist because retriers and catchers are evaluated in array order and the first one whose `ErrorEquals` contains a matching name wins. That ordering is the whole design pattern: name the specific, known-transient failures first with tuned settings, then let `States.ALL` be the backstop that keeps an unexpected failure from taking the execution down uncontrolled. ```json "Retry": [ { "ErrorEquals": ["Lambda.TooManyRequestsException"], "IntervalSeconds": 2, "BackoffRate": 2, "MaxAttempts": 6 }, { "ErrorEquals": ["States.ALL"], "MaxAttempts": 2 } ], "Catch": [ { "ErrorEquals": ["InventoryUnavailable"], "Next": "ReleaseHold" }, { "ErrorEquals": ["States.ALL"], "Next": "RecordFailure" } ] ``` ## The States.Runtime exception The one thing candidates miss: `States.Runtime` is documented as **not retriable**, and a retrier or catcher on `States.ALL` does **not** catch it. It always fails the execution. It is raised for failures Step Functions cannot process as ordinary task errors — for example applying an `InputPath` or `OutputPath` to a null payload. Practically this means "I put `States.ALL` on everything so nothing can fail" is false, and it is a good sign when a candidate volunteers that. ## Where custom error names come from Three common sources. A Lambda function that throws a typed exception surfaces that type as the error name, which is how you get domain names like `InventoryUnavailable` into `ErrorEquals`. A `Fail` state lets you set `Error` and `Cause` explicitly, which is how a workflow raises its own business failure. And AWS documents that *unhandled* Lambda errors — out-of-memory and function timeouts among them — surface as `Lambda.Unknown`, so a catcher written only for your own exception types will miss exactly the failures you most wanted to see. ## Why interviewers ask it It is a cheap probe for whether someone has actually written a failure path. Anyone who has will know the ordering rule from having had a definition rejected; anyone who has only read the marketing will describe `States.ALL` as an unconditional safety net.
- Are there errors that States.ALL will not catch?Yes — `States.Runtime`. AWS documents it as non-retriable and explicitly not matched by a retrier or catcher on `States.ALL`; it always fails the execution. It is raised for failures Step Functions cannot process as a normal task error, such as applying an `InputPath` to a null payload. So `States.ALL` is a broad backstop, not an absolute guarantee that nothing escapes.
- How do you get a domain-specific error name like PaymentDeclined into ErrorEquals?Two ways. Have the Lambda function throw a typed exception with that name — the exception type becomes the `Error` value the state reports, and you match it directly. Or raise it inside the workflow with a `Fail` state, which lets you set `Error` and `Cause` yourself. Both give you a name you can route on with a catcher instead of parsing `Cause` strings.
saying these in an interview costs you the question
- Claiming States.ALL catches absolutely every possible failure
- Listing States.ALL alongside specific names in one ErrorEquals
- Believing handlers are matched by specificity rather than array order
- Assuming ErrorEquals supports wildcards or prefixes like Lambda.*
- Thinking States. names are the only error names that exist