Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

ECS cannot run a task because the cluster has no container instances

ErrorNo Container Instances were found in your cluster

Short answer

For the EC2 launch type, a task needs a registered container instance. None are registered when the instance joined the default cluster instead of yours, lacks the ECS instance IAM role, cannot reach the ECS endpoint, or its agent is not running. List the cluster's instances first, then read the agent log.

  • Applies to Amazon ECS EC2 launch type, Amazon ECS-optimized AMI, AWS CLI v2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask ECS how many container instances the cluster really has. An empty list confirms the instances never registered.

    aws ecs list-container-instances --cluster my-cluster
    aws ecs list-container-instances --cluster default
  2. 2Match what you see, then jump to its fix

    1. 1my-cluster lists nothing, but the default cluster lists the instance.The instance joined the default cluster, not yoursFix
    2. 2The instance has no IAM instance profile attached.The instance has no ECS instance IAM roleFix
    3. 3The instance is in a private subnet with no public IP, NAT gateway or interface VPC endpoint.The instance cannot reach the ECS service endpointFix
    4. 4The instance shows in the cluster but RunTask returns an AGENT failure.The agent is not running or is disconnectedFix

What does the error look like?

  • No Container Instances were found in your cluster
  • TaskFailedToStart: EMPTY CAPACITY PROVIDER

Cause 1 of 4

The instance joined the default cluster, not yours

1Check

By default a container instance launches into the cluster named default. It joins another one only when ECS_CLUSTER is set in /etc/ecs/ecs.config.

sudo cat /etc/ecs/ecs.config

2Fix

Set the cluster name in the agent config and restart the agent. For a new instance put the same line in the launch user data.

echo ECS_CLUSTER=my-cluster | sudo tee -a /etc/ecs/ecs.config
sudo systemctl restart ecs

3Verify

List the instances of your cluster again.

aws ecs list-container-instances --cluster my-cluster

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 2 of 4

The instance has no ECS instance IAM role

1Check

ECS says the role lets the service know the agent belongs to you; without the proper IAM permissions the agent cannot connect to your cluster. The role is usually named ecsInstanceRole.

aws ec2 describe-instances --instance-ids i-0123456789abcdef0 \
  --query "Reservations[].Instances[].IamInstanceProfile.Arn"

2Fix

Create ecsInstanceRole with the AmazonEC2ContainerServiceforEC2Role managed policy, attach it to the instance as its instance profile, and restart the agent.

aws iam attach-role-policy \
  --role-name ecsInstanceRole \
  --policy-arn arn:aws:iam::aws:policy/service-role/AmazonEC2ContainerServiceforEC2Role

3Verify

Restart the agent and list the cluster's instances.

sudo systemctl restart ecs
aws ecs list-container-instances --cluster my-cluster

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 3 of 4

The instance cannot reach the ECS service endpoint

1Check

Container instances must reach the Amazon ECS endpoint, through an interface VPC endpoint, a public IP, or NAT.

sudo tail -n 40 /var/log/ecs/ecs-init.log

2Fix

Give the subnet a NAT gateway or an ECS interface VPC endpoint, or turn on Auto-assign Public IP for the instance in a public subnet.

# check the route table of the instance's subnet
aws ec2 describe-route-tables --filters Name=association.subnet-id,Values=subnet-0123456789abcdef0

3Verify

Restart the agent and check the instance registers.

sudo systemctl restart ecs
aws ecs list-container-instances --cluster my-cluster

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 4 of 4

The agent is not running or is disconnected

1Check

ECS keeps agent logs in /var/log/ecs on the instance. A disconnected agent makes ECS reject task placement.

sudo systemctl status ecs
sudo cat /var/log/ecs/ecs-init.log

2Fix

Restart the ECS agent, then read the log again if it does not come back.

sudo systemctl restart ecs

3Verify

The instance appears in the cluster list.

aws ecs list-container-instances --cluster my-cluster --status ACTIVE

Confirmed by docs.aws.amazon.com

Did this fix it?

How do I stop it coming back?

  • Put ECS_CLUSTER and the instance profile in the launch template, not in a one-time manual edit.
  • Keep ecsInstanceRole attached with the managed policy for every container instance.
  • Plan the subnet's route to ECS (NAT or endpoint) before launching private instances.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Servers

Apache has a certificate, but https:// does not open

No line with :443 in the output of ss -ltnp

HTTPS needs four things at once: mod_ssl loaded, Apache listening on 443, a virtual host on 443 with SSLEngine on, and a firewall that lets 443 in.

4 causes, each with a fix

Servers

AWS CLI says you must specify a region

You must specify a region. You can also configure your region by running "aws configure".

The AWS CLI sends every request to one region and has none to use.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.