# aws ecs run-task

AWS CLI commands · Updated 16 November 2026

**Short answer:** aws ecs run-task --cluster my-cluster --task-definition my-task --launch-type FARGATE --network-configuration "awsvpcConfiguration={subnets=[subnet-0123456789abcdef0],securityGroups=[sg-0123456789abcdef0]}" starts a standalone task, outside any service. Use --overrides to change the command for jobs such as database migrations, and check failures[] in the response.

## What the command does

`run-task` launches one or more copies (up to ten per call) of a task definition. Nothing restarts them when they exit, which makes it the right tool for migrations, batch jobs, one-off scripts and ad-hoc debugging containers.

The response has `tasks[]` for tasks that were placed and `failures[]` for those that were not. A placement failure does not make the command exit non-zero.

## Syntax

```
aws ecs run-task --cluster my-cluster --task-definition my-task[:rev] \
  [--launch-type FARGATE | --capacity-provider-strategy capacityProvider=FARGATE_SPOT,weight=1] \
  [--network-configuration "awsvpcConfiguration={subnets=[...],securityGroups=[...],assignPublicIp=DISABLED}"] \
  [--overrides file://overrides.json] \
  [--count 1] [--started-by my-job] [--enable-execute-command]
```

## Worked examples

**Run database migrations using the service's image**, overriding the command:

```
TASK=$(aws ecs run-task --cluster prod --task-definition orders-api \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-0aa0123456789abcd,subnet-0bb0123456789abcd],securityGroups=[sg-0123456789abcdef0],assignPublicIp=DISABLED}" \
  --overrides '{"containerOverrides":[{"name":"web","command":["python","manage.py","migrate"]}]}' \
  --started-by migrate-$(date +%s) \
  --query "tasks[0].taskArn" --output text)
```

**Wait and fail if the job failed**:

```
aws ecs wait tasks-stopped --cluster prod --tasks "$TASK"
CODE=$(aws ecs describe-tasks --cluster prod --tasks "$TASK" \
  --query "tasks[0].containers[?name=='web'].exitCode | [0]" --output text)
[ "$CODE" = "0" ] || { echo "migration failed with $CODE"; exit 1; }
```

**Pass extra environment variables and more memory** through an overrides file:

```
{
  "memory": "4096",
  "containerOverrides": [{
    "name": "web",
    "command": ["python", "scripts/backfill.py"],
    "environment": [{ "name": "BACKFILL_FROM", "value": "2026-11-01" }]
  }]
}
```

Task-level CPU and memory overrides must still be a valid Fargate combination.

**A debugging shell** you can exec into:

```
aws ecs run-task --cluster prod --task-definition toolbox --launch-type FARGATE \
  --enable-execute-command \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-0aa0123456789abcd],securityGroups=[sg-0123456789abcdef0]}"
```

## Failures and fixes

| Symptom | Cause |
|---|---|
| `failures[].reason` = `RESOURCE:MEMORY` or `RESOURCE:CPU` | EC2 launch type: no instance with enough free capacity. |
| `InvalidParameterException: Network Configuration must be provided` | Fargate and `awsvpc` tasks need `--network-configuration`. |
| Task stops with `CannotPullContainerError` | Private subnet without NAT or VPC endpoints, or public subnet with `assignPublicIp=DISABLED`. |
| `AccessDeniedException` on `iam:PassRole` | Your identity needs permission to pass the task and execution roles. |

## Gotchas

- **Container names in overrides must match** the task definition exactly, or the override is rejected.
- **Overrides replace, not append.** A `command` override replaces the whole command array; `environment` entries add to or replace variables by name.
- **Waiter limits.** `tasks-stopped` gives up after about ten minutes; long jobs need a polling loop on `lastStatus`.
- **Scheduled tasks not running?** EventBridge rules and Scheduler schedules call this same API; check the target's role permissions and network configuration, and the rule's failed invocation metrics.
- **Label your tasks.** A meaningful `--started-by` value, such as the job name and a timestamp, lets you find the task later with `list-tasks --started-by` and makes CloudTrail and task events easier to read.

## Questions

### How do I override the command in aws ecs run-task?

Use --overrides with containerOverrides, naming the container and giving a command array, for example {"containerOverrides":[{"name":"web","command":["npm","run","migrate"]}]}.

### Why is my ECS scheduled task not running?

Check the EventBridge target's role can call ecs:RunTask and pass the task roles, that the network configuration is valid for Fargate, and the rule's FailedInvocations metric.

### How do I get the exit code of a task started with run-task?

Wait with aws ecs wait tasks-stopped, then read tasks[0].containers[].exitCode from describe-tasks.

## When this happens away from your desk

One-off jobs such as migrations are often run during incidents, sometimes under pressure. CloudConsole, a phone app for AWS, is built with production guardrails and to show task outcomes and logs on a phone.

[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

- [AWS CLI Command Reference: ecs run-task](https://docs.aws.amazon.com/cli/latest/reference/ecs/run-task.html)
- [RunTask API reference](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html)

## Related

- [aws ecs describe-tasks](https://cloudconsole.dev/cli/ecs-describe-tasks)
- [aws ecs register-task-definition](https://cloudconsole.dev/cli/ecs-register-task-definition)
- [aws ecs execute-command](https://cloudconsole.dev/cli/ecs-execute-command)
- [CannotPullContainerError: pull image manifest has been retried](https://cloudconsole.dev/errors/ecs-cannotpullcontainererror)
- [service was unable to place a task because no container instance met all of its requirements](https://cloudconsole.dev/errors/ecs-unable-to-place-task)
- [aws ecs describe-services](https://cloudconsole.dev/cli/ecs-describe-services)

---

Source: https://cloudconsole.dev/cli/ecs-run-task

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