AgentDisconnected on ECS: what causes it and how to fix

By Sai Kiran Pandrala · Last verified: 2026-05-31 · Source: AWS docs, AWS re:Post, community Q&A

Engineers running Amazon ECS hit AgentDisconnected on ECS, what causes it and how to fix often enough that there is a stable fix pattern. This page captures it in the order AWS support would run it during a real incident.

What agentdisconnected on ecs, what causes it and how to fix actually involves on Amazon ECS

The AgentDisconnected error from AWS typically surfaces with the message "The container instance has been disconnected from the ECS service". The error code itself is what you grep for in AWS re:Post or in AWS Support cases, not the human-readable line.

On ECS, this most often comes from one of three causes: a missing or restrictive IAM permission, a service-level limit you have hit, or a transient AWS-side capacity issue. The fix path differs by which.

The rest of this page is the structured fix path. Start with diagnose, then remediation, then the automation options so you do not have to do this by hand the next time it surfaces. Verify and safety sections at the end are the discipline that keeps the fix from regressing in production.

Signal review

Check the AWS Health Dashboard at health.aws.amazon.com for ongoing service events in your region. About one in ten user-reported outages turn out to be region-scoped AWS service degradation already being tracked. AWS Health also exposes an API and EventBridge events, so you can wire a Lambda hook that pages on-call only when the failure correlates with an active AWS Health event in the same region and service.

Run aws sts get-caller-identity first. About one in five 'why does this not work' tickets are actually 'I am in the wrong account' or 'my session expired and the SDK is using stale creds'. The 5-second sanity check costs nothing and saves real time when the answer is that simple.

Start by capturing the exact AWS error string. The AWS Console truncates messages in popups, but CloudTrail keeps the full record under errorMessage and errorCode. The camelCase error code (e.g. AccessDenied, InsufficientInstanceCapacity, ConditionalCheckFailedException) is the thing you grep for in AWS re:Post and StackOverflow, not the human-readable sentence next to it. Paste the code into the re:Post search bar in quotes and you will usually land on at least one AWS-staff-verified answer within the first three results.

Solution-focused remediation path

If networking is suspect, use VPC Reachability Analyzer. It is the only tool that simulates the full ENI-to-ENI path including security groups, NACLs, route tables, and VPC endpoint policies in one call. Manual trace is slower and misses transitive issues. The analyzer charges $0.10 per analysis - cheaper than a 30-minute call with your network team.

If quotas are suspect, the Service Quotas console shows current usage and the active limit side by side. Request increases through Service Quotas, not through Support tickets - quota dashboard requests usually approve faster (often within minutes for soft limits) and they are auditable in CloudTrail. Set up Service Quotas + CloudWatch alarms at 80 percent usage so you get notified before you hit the wall.

Most Amazon ECS failures fall into one of three buckets: IAM permission gap, networking path break (security group, NACL, or VPC endpoint policy), or service-limit / quota hit. Run that mental triage first - it covers around 80 percent of real-world cases. If the failure does not fit any of the three, it is likely a service-side regression worth opening a re:Post or support ticket for.

Automate this fix so you do not do it twice

Add a Systems Manager Automation runbook

For multi-step fixes that include a manual approval, use SSM Automation. Document the fix as a runbook with aws:approve steps where a human signs off and aws:executeAwsApi steps where the runbook calls the AWS API. Approvers are notified by SNS; the runbook execution shows up in CloudTrail with the approver's identity attached. This makes audit trails easy and stops production fixes from being one-person operations.

Automate the fix with Python and boto3

For anything you do more than twice, write a small Python script. The boto3 pattern below uses paginators (so it does not blow up on accounts with thousands of resources), explicit region binding, and a dry-run flag that defaults to True. Keep the script under 100 lines; if it grows beyond that, you are building a tool and should put it behind a Lambda with proper logging.

import boto3, sys
DRY_RUN = '--apply' not in sys.argv
client = boto3.client('ecs', region_name='us-east-1')
paginator = client.get_paginator('describe_...')
for page in paginator.paginate(): for item in page.get('Items', []): if item.get('Status') == 'FAILED': if DRY_RUN: print(f'[dry-run] would fix {item["Id"]}') else: client.modify_...(ResourceId=item['Id']) print(f'fixed {item["Id"]}')

Automate the fix with the AWS CLI

The CLI one-liner pattern for Amazon ECS operations is roughly: aws ecs describe-... --query ... to read state, aws ecs modify-... --no-dry-run to apply the change, and aws ecs describe-... --query ... again to verify. Wrap it in a shell script that sets a region variable at the top and exits on first error with set -euo pipefail so a partial run does not leave the account in a half-fixed state.

# Template - replace placeholders with your account specifics
export AWS_REGION=us-east-1
export AWS_PROFILE=prod
aws ecs describe-... --query 'Resources[?Status==`FAILED`].[Id,Reason]' --output table
aws ecs modify-... --resource-id RESOURCE_ID --no-dry-run
aws ecs describe-... --resource-id RESOURCE_ID --query 'Status'

Things that bite

A subtle pitfall on Amazon ECS is that the AWS Console and the SDK can disagree about resource state during a configuration change. Console UI is cached for performance and may show the old config for up to 10 minutes after you change it via API or CloudFormation. Always confirm with describe-* CLI calls during a change window, not with screenshots from the Console.

The other pitfall: assuming that an automated remediation is correct because it succeeded. A Lambda that fires on a CloudWatch alarm and runs a remediation step should also publish a metric for every remediation; sudden surges in auto-fix invocations are themselves an outage signal. Otherwise you can hide a slow-burn regression behind a quiet remediation loop for weeks.

Repair sequence

• Reproduce the original symptom path. If it still surfaces in any account or region or IAM role, you have not fixed it.
• Watch for 24 to 48 hours. AWS metrics and policy systems can mask issues with cached health for 6 to 12 hours, especially CloudFront and Route 53.
• Run a smoke test under realistic load. Happy-path tests miss race conditions and IAM session-cache issues.
• Capture the new state in a runbook so the next person on call does not have to rediscover this. Push it to Confluence or your team wiki, not into Slack.
• If the fix involved a permission change, run IAM Access Analyzer one more time to confirm you did not open a separate hole while closing this one.

Safety, rollback, blast radius

• Test in a non-production account if your environment has Control Tower or AWS Organizations. The cost of one sandbox account is cheaper than one rollback meeting.
• Export the existing config before changing it. Most Amazon ECS resources support describe + export to JSON via CLI - capture that to source control before you start.
• Know your rollback path. Some Amazon ECS operations are one-way (region migration, account-level feature opt-in, KMS key deletion past pending window). Confirm reversibility on the AWS doc before you commit.
• Be aware of cross-service impact. IAM role changes ripple to every service trusting that role. KMS key changes break every workload depending on that key. VPC endpoint changes affect every VPC consumer of that endpoint.
• Maintenance window discipline: if the change touches DNS, certificate rotation, or anything that emits TLS handshakes, line up a window with stakeholder notification, not a heroic mid-day swap.

FAQ

Related fixes

Related guides worth a look while you sort this one out:

• CannotPullContainerError on ECS. what causes it and how to fix
• CannotPullECRContainerError on ECS. what causes it and how to fix
• ContainerRuntimeError on ECS. what causes it and how to fix
• DockerTimeoutError on ECS: what causes it and how to fix
• EssentialContainerExited on ECS. what causes it and how to fix
• HealthCheckTimeout on ECS, what causes it and how to fix