SAM Doctor

ERROR REFERENCE

ECS Exec could not start the managed agent

ECS could not start the managed SSM agent required by execute-command. Check the task's reported state and the prerequisites before changing permissions blindly.

WHAT IT MEANS

What this error means

CannotStartManagedAgentError: failed to start managed agent inside container

The same condition can surface as an InvalidParameterException saying that Exec was not enabled when the task ran or that the execute-command agent is not running. The wrapper does not identify whether the task flag, task role, network, agent, or filesystem is the missing prerequisite.

NEXT CHECK

Read the task state, then fix the prerequisite

  1. Inspect the task without changing it: 
    aws ecs describe-tasks --cluster <cluster> --tasks <task>
    Confirm enableExecuteCommand is true and the ExecuteCommandAgent managed agent reports lastStatus: RUNNING with no failure reason.
  2. Check launch-time prerequisites. Enable Exec before launching this task, give its task role the required ssmmessages channel actions, and provide network access to the Systems Manager Message Gateway or its VPC endpoint.
  3. Keep the container filesystem writable. ECS Exec does not support readonlyRootFilesystem; a mount that hides the managed-agent paths can produce the same startup failure. Launch a new task after changing the task definition.

AUTOMATE THE TRIAGE

Keep the check in your normal workflow

SAM Doctor recognizes the ECS Exec handoff with medium confidence and points at the task-state, SSM, network, and filesystem checks. Runs locally; no AWS access, no log upload. 

python -m pip install sam-doctor
sam-doctor diagnose deployment.log --format markdown

RELATED