CloudConsole

Step Functions States.Timeout / States.TaskFailed

Updated 17 November 2026 · How we write and check guides

Short answer

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.

Common causes, in 4 steps: 1. Callback never arrives; 2. Timeout shorter than the work; 3. Downstream errors; 4. Express…
The diagnosis and fix steps from this page, in the order to try them; commands and details are below.

What the errors mean

ErrorRaised when
States.TimeoutA Task ran longer than its TimeoutSeconds, or the execution exceeded the state machine's top-level TimeoutSeconds
States.HeartbeatTimeoutA task using HeartbeatSeconds (typically an activity or .waitForTaskToken) did not send a heartbeat in time
States.TaskFailedA Task failed. In Retry and Catch it also acts as a wildcard for any task error except States.Timeout
States.ALLNot 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 table

Look 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 20

Common causes

  • Callback never arrives: a .waitForTaskToken task whose worker crashed or never called SendTaskSuccess. Without a timeout it can wait for a very long time; with one it fails with States.Timeout.
  • Timeout shorter than the work: a Task TimeoutSeconds lower 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 TimeoutSeconds on every Task, and HeartbeatSeconds on 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.

CloudConsole home screen showing what needs attention on a phone, for following up on Step Functions States.Timeout /…
When this happens away from your desk

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

Sources