Step Functions States.Timeout / States.TaskFailed
States.Timeout means a state ran longer than its TimeoutSeconds (or the whole execution exceeded its timeout); States.TaskFailed is the generic error for a Task that failed. Read the execution history to find the failing state and its cause, then fix the task, give it a realistic timeout or heartbeat, and add Retry and Catch for errors you expect.
What the errors mean
| Error | Raised when |
|---|---|
States.Timeout | A Task ran longer than its TimeoutSeconds, or the execution exceeded the state machine's top-level TimeoutSeconds |
States.HeartbeatTimeout | A task using HeartbeatSeconds (typically an activity or .waitForTaskToken) did not send a heartbeat in time |
States.TaskFailed | A Task failed. In Retry and Catch it also acts as a wildcard for any task error except States.Timeout |
States.ALL | Not raised; matches every error name in Retry and Catch |
Lambda tasks often fail with more specific names, such as the function's own exception type or Lambda.ServiceException and Lambda.TooManyRequestsException, which you can retry selectively.
Find the failing state
aws stepfunctions describe-execution \
--execution-arn arn:aws:states:eu-west-2:123456789012:execution:order-flow:4f1c2e \
--query '{status:status,error:error,cause:cause}'
aws stepfunctions get-execution-history \
--execution-arn arn:aws:states:eu-west-2:123456789012:execution:order-flow:4f1c2e \
--reverse-order --max-results 15 \
--query 'events[].[timestamp,type,taskFailedEventDetails.error,taskFailedEventDetails.cause]' \
--output tableLook for TaskTimedOut, TaskFailed, LambdaFunctionFailed or ExecutionTimedOut events; the cause often contains the downstream error message or stack trace. To see how widespread it is:
aws stepfunctions list-executions \
--state-machine-arn arn:aws:states:eu-west-2:123456789012:stateMachine:order-flow \
--status-filter TIMED_OUT --max-results 20Common causes
- Callback never arrives: a
.waitForTaskTokentask whose worker crashed or never calledSendTaskSuccess. Without a timeout it can wait for a very long time; with one it fails withStates.Timeout. - Timeout shorter than the work: a Task
TimeoutSecondslower than the Lambda function's real duration, or than a Glue or ECS job's runtime. - Downstream errors: Lambda exceptions, throttling, permissions on the state machine's role, or an SDK integration returning a validation error; all surface as task failures.
- Express workflows have a five-minute maximum duration, so long jobs time out regardless of state settings.
Fix with timeouts, Retry and Catch
"ChargeCard": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Parameters": { "FunctionName": "charge-card", "Payload.$": "$" },
"TimeoutSeconds": 30,
"Retry": [
{ "ErrorEquals": ["Lambda.ServiceException", "Lambda.TooManyRequestsException"],
"IntervalSeconds": 2, "MaxAttempts": 3, "BackoffRate": 2 },
{ "ErrorEquals": ["States.Timeout"], "MaxAttempts": 1 }
],
"Catch": [
{ "ErrorEquals": ["States.ALL"], "ResultPath": "$.error", "Next": "NotifyFailure" }
],
"Next": "ShipOrder"
}- Set
TimeoutSecondson every Task, andHeartbeatSecondson callback and activity tasks so a dead worker is detected quickly. - Retry only transient errors; retrying a validation error just delays the failure.
- Keep the Lambda function's own timeout below the Task timeout, so you get the function's error instead of a bare
States.Timeout. - Make retried tasks idempotent: a timed-out task may still have completed its side effect.
Alarm on it
Step Functions publishes ExecutionsFailed and ExecutionsTimedOut per state machine in the AWS/States namespace. Alarm on both, and route the Catch branch to a notification so a business failure is visible even when the execution is marked succeeded.
Questions
What is the difference between States.Timeout and States.TaskFailed?
States.Timeout is raised when a state or execution exceeds its configured timeout. States.TaskFailed is raised when a task fails for another reason; in Retry and Catch it matches any task error except States.Timeout.
How do I retry a Step Functions task on timeout?
Add a Retry entry with ErrorEquals ["States.Timeout"] and MaxAttempts, and make sure the task is idempotent because the timed-out attempt may still have finished its work.
What are the CloudWatch alarm states?
A CloudWatch alarm is always in one of three states: OK, ALARM or INSUFFICIENT_DATA. Alarm actions run when it changes into the state you attach them to.

Failed workflow executions often mean orders or jobs quietly stuck halfway. CloudConsole, a phone app for AWS, is built to show failed and timed-out execution alarms on your phone, so stuck work is noticed while it can still be retried.
Did it start after a deploy? What changed? on the app’s alarm screen lists the deploys and configuration changes from the hour before the alarm fired.
About the app → · Download on the App Store