How can I troubleshoot Systems Manager maintenance windows failures?

Short description

Use maintenance windows to set up a schedule to perform potentially disruptive actions on your instances. For more information, see AWS Systems Manager maintenance windows.

Note: Maintenance windows tasks require an AWS Identity and Access Management (IAM) entity role (role or user) with the required permissions. For more information, see Setting up maintenance windows.

Resolution

To troubleshoot maintenance windows failures, complete the following tasks based on your error message.

"Unable to assume the provided role"

The Systems Manager maintenance window task can't assume the IAM service role set for the task. Select a service role that allows Systems Manager maintenance windows to interact with other AWS services on your behalf. Make sure that the trusted relationship policy for the role allows the service ssm.amazonaws.com. This Principal policy element is required for the Systems Manager task to assume the specified IAM role.

To check the trust relationship policy and update it, complete the following steps:

1. Open the IAM console.

2. In the navigation pane, choose Roles.

3. Choose the role that you included in your task definition, and then choose the Trust relationships tab.

4. Choose Edit trust policy.

5. Copy and paste the following trust policy into the edit pane:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "",
         "Effect": "Allow",
         "Principal": {
           "Service": "ssm.amazonaws.com"
         },
         "Action": "sts:AssumeRole"
       }
     ]
   }

6. Choose Update policy.

"The provided role does not contain the correct SSM permissions"

This error occurs when you specify a maintenance window service role for a task, but the task fails to successfully run. To resolve this error, provide additional permissions in the IAM policy for your maintenance window role.

To provide additional permissions, complete the following steps:

1. Open the IAM console.
2. In the navigation pane, choose Roles.
3. Choose the role that you included in your task definition, and then choose the Trust relationships tab.
4. Add the required permissions to the role.

For more information, see Task fails with task invocation status: "The provided role does not contain the correct SSM permissions."

"No Instances in Tag"

This error occurs when the instance tag key value is missing or incorrect for the maintenance window tag key-value pairs.

To edit the instance tag key value, complete the following steps:

1. Open the Systems Manager console.
2. In the navigation pane, choose Maintenance Window.
3. In Maintenance windows, choose your window ID.
4. Choose the Targets tab.
5. In Window target ID, select your target ID, and then choose Edit.
6. In Targets, Check the instance tags specified.
7. If the maintenance window tag key-value pairs match your requirements, then update your instance with these key-value pairs.

"The specified parameters are incomplete or invalid"

This error means that a required parameter value is either missing or isn't valid with the maintenance window Automation task. To resolve this issue, see How do I add parameters when registering an Automation task with Systems Manager maintenance windows?

"Failed"

If you exceed the rate control limit in Run Command, then you might get a timeout issue. Increase the maximum error rate control limit to a higher number. You can also specify an absolute number of errors, or a percentage of the target set. For more information, see How do I troubleshoot Systems Manager Run Command timeout issues?

Related information

Troubleshooting maintenance windows

How do I configure maintenance windows for patching Amazon EC2 and hybrid nodes in multiple environments using Systems Manager?

How can I use Systems Manager Maintenance Windows to schedule my EC2 instances to start and stop?

How do I troubleshoot Systems Manager Run Command failures?