How do I troubleshoot Systems Manager Run Command timeout issues?

Short description

To troubleshoot timeout errors related to Run Command, review your command's status details and AWS Systems Manager Agent (SSM Agent) logs. Then troubleshoot the timeout error based on your findings.

Run Command timeout status details include the following values:

• Execution timeout
  The Systems Manager document defines the default Execution timeout value. For example, the AWS-RunShellScript document uses a default of 3600 seconds (1 hour). The maximum execution timeout value is 172800 seconds (48 hours).
• Delivery timeout
  You specify the Delivery timeout value when you send the command. Use the console's Timeout (seconds) field or the SendCommand API call. Systems Manager didn't deliver the command to the managed node before the delivery timeout expired. The default delivery timeout is 600 seconds (10 minutes).
• Total timeout
  The Total timeout value is the sum of the delivery timeout value plus the execution timeout value. If you don't specify an execution timeout is in the Systems Manager document, then Systems Manager uses the default execution timeout value. .

Note: A DeliveryTimedOut status means SSM Agent didn't receive the command before the delivery timeout expired. An ExecutionTimedOut status means the command started to run but didn't complete within the execution timeout period.

For a list of Run Command Status details, see Understanding command statuses.

Resolution

Complete the following steps:

1. Open the Systems Manager console.
2. In the navigation pane, select Run Command.
3. (Optional) to check a Run command that you used in the past, choose the Command history tab.
4. Choose the Command ID that corresponds with your command to open the Command status page.
5. From the Targets and outputs section, choose the Instance ID that corresponds to your Amazon EC2 instance, and then review the output.

If the output is truncated, then use SSH to and then navigate to the following directories to see the full error details:
Important: Some plugins run only on either Windows Server instances or Linux instances. For a list of plugins that you can specify in command documents, and each plugin's platform dependencies, see Command document plugin reference.
For Linux and macOS:

• /var/lib/amazon/ssm/example-instance-ID/document/orchestration/example-command-id/example-plugin-name/example-step-name/stdout
• /var/lib/amazon/ssm/example-instance-ID/document/orchestration/example-command-id/example-plugin-name/example-step-name/stderr

For Windows:

• %ProgramData%\Amazon\SSM\InstanceData\example-instance-ID\document\orchestration\example-command-id\example-plugin-name\example-step-name\stdout
• %ProgramData%\Amazon\SSM\InstanceData\example-instance-ID\document\orchestration\example-command-id\example-plugin-name\example-step-name\stderr

Note: Replace example-instance-ID with your EC2 instance's ID number. Replace example-command-ID, with your command ID. Replace example-plugin-name with the name of the plugin that you specify in your Command document. Replace example-step-name with the name value that corresponds with the plugin that you specify in the mainSteps section of your Command document.

Review the exit status codes in your exit details then use your exit status codes to troubleshoot Run Command.

Review SSM Agent logs

Review your SSM Agent logs for more details about the failure.

Note: The AWS Systems Manager CloudWatch Dashboard will no longer be available after April 30, 2026. You can continue to use Amazon CloudWatch console to view, create, and manage your CloudWatch dashboards. For more information, see Using Amazon CloudWatch dashboards.

If the SSM Agent logs don't provide the information that you need to resolve the error, then allow debug logging to reproduce the issue.

Troubleshoot timeout issues

Take the following actions:

• Verify that your command completes within both timeout periods. The execution timeout is the time for the command to run. The delivery timeout is the time for the command to reach the managed node. The execution timeout is defined in the SSM document or the console's Execution Timeout field. The delivery timeout is the value you enter in the console's Timeout (seconds) field. You can also specify it in the SendCommand API call's timeout parameter. For more information about how to configure your timeout values, see Handling timeouts in runbooks.
• If your instance doesn't display as a managed node, or your SSM Agent ping status isn't Online, then troubleshoot your offline SSM Agent or instance.
• If your Run Command runs scripts that reboot managed nodes, then the node might disconnect and cause timeout issues. Make sure that you use the correct exit codes. For more information, see Handling reboots when running commands.
• Verify that SSM Agent functions correctly. For information, see Troubleshooting SSM Agent.
• Verify that you use the latest version of SSM Agent. You can configure SSM Agent to update automatically.
  Note: SSM Agent version 2.0.913.0 and later supports a maximum execution timeout value of 172800 seconds (48 hours).
• Use AWS CloudTrail to review the SendCommand API call's response when you run a command with Maintenance Window or State Manager, capabilities of AWS Systems Manager. In the output, verify that the command successfully runs.

Related information

AWS Systems Manager documents

Setting up managed nodes for AWS Systems Manager

How do I troubleshoot Systems Manager Run Command failures?