Maaz Zindani

Loading the index…

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

SSM SendCommand fails with InvalidInstanceId for an EC2 instance

Errorbotocore.errorfactory.InvalidInstanceId: An error occurred (InvalidInstanceId) when calling the SendCommand operation

Short answer

InvalidInstanceId means Systems Manager does not see that instance as a managed node. Check the instance state, whether SSM Agent runs and registered, that an IAM instance profile with AmazonSSMManagedInstanceCore is attached, that the instance reaches the SSM endpoints on port 443, and that you use the same region.

  • Applies to boto3 1.x, AWS CLI 2, Amazon Linux 2023, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask Systems Manager whether the agent registered. This command returns nothing until a successful registration, so an empty list means the instance is not a managed node yet.

    aws ssm describe-instance-associations-status --instance-id i-0123456789abcdef0 --region us-east-1
  2. 2Match what you see, then jump to its fix

    1. 1the registration check returns an empty list, and the instance has no IAM roleThe instance has no IAM instance profile for Systems ManagerFix
    2. 2The profile is attached but the instance is still not listedSSM Agent is not running or never registeredFix
    3. 3Agent is running but the instance is in a private subnet with no outbound routeThe instance cannot reach the Systems Manager endpointsFix
    4. 4The ID is correct in the console but the call still failsWrong region, or the instance is shutting down or terminatedFix

What does the error look like?

  • botocore.errorfactory.InvalidInstanceId: An error occurred (InvalidInstanceId) when calling the SendCommand operation

Cause 1 of 4

The instance has no IAM instance profile for Systems Manager

1Check

An EC2 instance needs an instance profile so the agent can talk to the service. The usual policy is AmazonSSMManagedInstanceCore.

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

2Fix

In the EC2 console, attach an IAM role whose permissions include AmazonSSMManagedInstanceCore (or an equivalent custom policy) to the instance. Wait about five minutes for the agent to register.

# EC2 console: Actions > Security > Modify IAM role, then pick a role with AmazonSSMManagedInstanceCore

3Verify

The registration check now returns results instead of an empty list.

aws ssm describe-instance-associations-status --instance-id i-0123456789abcdef0

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 2 of 4

SSM Agent is not running or never registered

1Check

On the instance, look at the agent service state. The API page says to verify the agent runs and to reinstall it if it never registered.

sudo systemctl status amazon-ssm-agent

2Fix

Restart the agent. If it will not register, reinstall it with the AWS instructions for your OS.

sudo systemctl restart amazon-ssm-agent

3Verify

After a few minutes the registration check returns results.

aws ssm describe-instance-associations-status --instance-id i-0123456789abcdef0 --region us-east-1

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 3 of 4

The instance cannot reach the Systems Manager endpoints

1Check

Registration needs outbound HTTPS (port 443) to the service endpoints, or VPC interface endpoints for Systems Manager. A TLS test against the regional endpoint should answer with UnknownOperationException, not an SSL error.

curl -L https://ssm.us-east-1.amazonaws.com

2Fix

Allow outbound 443 through a NAT gateway or internet gateway, or create the Systems Manager VPC interface endpoints. Check the agent's proxy settings if you use a proxy.

# Console or IaC change: add the VPC interface endpoints for Systems Manager, or an outbound HTTPS route

3Verify

The registration check returns results.

aws ssm describe-instance-associations-status --instance-id i-0123456789abcdef0

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 4 of 4

Wrong region, or the instance is shutting down or terminated

1Check

The call must go to the Region where the instance lives. SendCommand also rejects instances that are shutting down or terminated; running, pending, stopped and stopping are valid states.

aws ec2 describe-instances --instance-ids i-0123456789abcdef0 --region us-east-1 \
  --query "Reservations[].Instances[].State.Name"

2Fix

Pass the right region to the client (region_name in boto3, --region in the CLI) and use a live instance.

import boto3
ssm = boto3.client("ssm", region_name="us-east-1")

3Verify

Run a harmless command and read its status.

aws ssm send-command --instance-ids i-0123456789abcdef0 \
  --document-name "AWS-RunShellScript" \
  --parameters 'commands=["hostname"]' --region us-east-1

Confirmed by docs.aws.amazon.com

Did this fix it?

How do I stop it coming back?

  • Bake SSM Agent and an SSM instance profile into your launch template or AMI.
  • In automation, call describe-instance-associations-status first and wait until it returns results.
  • Keep the region in one config value used by both EC2 and SSM clients.
  • Add VPC endpoints for Systems Manager when you run instances in private subnets.

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

Servers

EC2 Instance Connect from the browser will not open an SSH session

Host key validation failed for EC2 Instance Connect

Browser-based EC2 Instance Connect needs five things at once: a fresh host key in the AWS database, a current agent package, port 22 open to the EC2 Instance Connect prefix list, a public address with a route (or an Instance Connect Endpoint), and a browser that can reach the proxy on port 443.

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