# Step Functions States.Timeout / States.TaskFailed

AWS error fixes · Updated 17 November 2026

**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.

## 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 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.

## 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.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [Handling errors in Step Functions workflows](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-error-handling.html)
- [AWS Step Functions Developer Guide](https://docs.aws.amazon.com/step-functions/latest/dg/)

## Related

- [Lambda: Task timed out after 3.00 seconds](https://cloudconsole.dev/errors/lambda-task-timed-out)
- [aws cloudwatch put-metric-alarm](https://cloudconsole.dev/cli/cloudwatch-put-metric-alarm)
- [aws cloudwatch describe-alarms](https://cloudconsole.dev/cli/cloudwatch-describe-alarms)
- [TooManyRequestsException: Rate Exceeded (Lambda throttling)](https://cloudconsole.dev/errors/lambda-toomanyrequests-rate-exceeded)
- [How to get CloudWatch alarm email notifications](https://cloudconsole.dev/how-to/cloudwatch-alarm-email-notification)
- [How to redrive a Step Functions execution](https://cloudconsole.dev/how-to/redrive-step-functions-execution)

---

Source: https://cloudconsole.dev/errors/stepfunctions-states-timeout

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
