How do I troubleshoot “Incorrect function” errors when SSM Agent startup fails?

Short description

On Amazon Elastic Compute Cloud (Amazon EC2) Windows instances, SSM Agent requires access to the Amazon EC2 Instance Metadata Service (IMDS) at the 169.254.169.254 IP address. SSM Agent uses the EC2 IMDS to retrieve necessary instance identity information and AWS Identity and Access Management (IAM) credentials. If SSM can't access the necessary information and credentials, then SSM Agent startup fails and you receive an “Incorrect function” error message.

To resolve SSM Agent access to IMDSv1 and IMDSv2, take the following actions:

• Verify that you correctly configured the connectivity between IMDS and network routes.
• Make sure that you use the correct proxy configuration.
• Confirm that you use the latest versions of EC2 Launch.

Resolution

Prerequisite: Make sure that you use the latest version of SSM Agent. For instructions, see Manually installing and uninstalling SSM Agent on EC2 instances for Windows Server. It's a best practice to configure automatic updates for SSM Agent. If your SSM Agent installation corrupted, then reinstall SSM Agent. For detailed installation instructions, see Working with SSM Agent on EC2 instances for Windows Server.

Take the following actions to resolve the “Incorrect function” error message and other issues related to SSM Agent startup failures on Windows instances.

Resolve IMDS connectivity and route configuration issues

IMDS provides SSM Agent with the necessary instance information and IAM credentials to communicate with Systems Manager. If your instance configuration lacks routes to IMDS or routes point to an incorrect gateway, then SSM Agent fails to start.

IMDS connectivity

Complete the following steps:

To verify IMDS connectivity, open PowerShell as an administrator, and then run the following command:

Invoke-RestMethod -Uri http://169.254.169.254/latest/dynamic/instance-identity/document

If the output includes your instance details, then SSM Agent can connect to IMDS. If the output has a connection timeout or error messages, then SSM Agent can't connect to IMDs. Then, you must check your route configuration.

Check that you correctly configured the routes

To check your route configuration, run the following command:

route print

In the output, check that the routes for 169.254.169.254 IP addresses exist and that they point to the correct gateway.

To display your network configuration, run the following command:

ipconfig /all

In the output, verify that the default gateway matches your subnet's gateway.

If routes for 169.254.169.254 addresses are missing or point to an incorrect gateway, then note your subnet's default gateway IP address value next to Default Gateway. To fix incorrect routes, complete the following steps:

1. To delete incorrect persistent routes to IMDS-related addresses, run the following command:

   route DELETE 169.254.169.254  
   

   Note: Run the command for each incorrect persistent route in your configuration to manually delete every incorrect route.

2. To use the EC2Launch module to add correct routes, run the following command:

   Import-Module c:\ProgramData\Amazon\EC2-Windows\Launch\Module\Ec2Launch.psm1 ; Add-Routes

   If the EC2Launch module isn't available, then manually add the persistent route. Run the following command:

   route -p ADD 169.254.169.254 MASK 169.254.169.254 example-subnet-default-gateway

   Note: Replace example-subnet-default-gateway with your subnet's default gateway IP address.

3. Run the following query to verify that you correctly configured the routes:

   route print

4. Run the following command in PowerShell to start SSM Agent:

   Start-Service AmazonSSMAgent

Resolve proxy configurations that block IMDS access

When you configure a proxy on the Windows instance, SSM Agent routes all traffic through the proxy, including requests to IMDS. SSM Agent only works correctly when your proxy configuration exclude the IMDS IP address.

To identify proxy issues, complete the following steps:

1. To navigate to the SSM installation directory, run the following command:

   cd 'C:\Program Files\Amazon\SSM'

   Note: If this directory doesn't exist, then SSM Agent may not be installed correctly. If you don't see the directory, then verify that you correctly installed SSM Agent again.

2. To troubleshoot the availability of your managed node, run the following ssm cli get-diagnostics command:

   .\ssm-cli.exe get-diagnostics --output table

3. Review your SSM Agent logs at **%PROGRAMDATA%\Amazon\SSM\Logs\**for proxy-related errors, such as "failed to get IMDSv2 token," "403 Forbidden," and "EC2MetadataError".

If your proxy settings block IMDS access, then run the following command to configure the proxy to skip IMDS requests:

netsh winhttp set proxy proxy-server="hostname:port" bypass-list="169.254.169.254”

Note: Replace hostname:port with your proxy server's IP address.

If you don't need to use your proxy, then run the following command to reset the proxy configuration:

netsh winhttp reset proxy

If you use persistent proxy configuration, then set the no_proxy value in the following registry key to 169.254.169.254:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\AmazonSSMAgent\Environmen

After you reconfigure your proxy configuration, run the following command to restart SSM Agent:

Restart-Service AmazonSSMAgent

After you restart SSM Agent, run the following commands to test your connectivity to each of the three necessary Systems Manager endpoints:

• For ssm:

  Test-NetConnection ssm.example-region.amazonaws.com -Port 443

• For ec2messages:

  Test-NetConnection ec2messages.example-region.amazonaws.com -Port 443

• For ssmmessages:

  Test-NetConnection ssmmessages.example-region.amazonaws.com -Port 443

Note: Replace example-region with your AWS Region ID.

For detailed guidance on proxy configuration, see Configure SSM Agent to use a proxy for Windows Server instances.

Outdated EC2Launch version

If you use an outdated EC2Launch utility, then the utility prevents route configuration and IMDS connectivity, and then results in SSM Agent startup failures.

To update EC2Launch, complete the following steps:

1. Check that you installed the current version of EC2Launch on the instance. If EC2Launch is outdated, then download and install the latest version based on your Windows Server version:
   For Windows Server 2012 R2 and earlier, use the manual route commands in the preceding IMDS connectivity and route configuration issues section of this article.
   For Windows Server 2016 and 2019, use EC2Launch.
   For Windows Server 2022 and later, use EC2Launch v2.

2. After you update EC2Launch, run the following command to restart the EC2Launch service:

   Restart-Service EC2Launch

3. To add your metadata routes, run the following command:

   Import-Module c:\ProgramData\Amazon\EC2-Windows\Launch\Module\Ec2Launch.psm1 ; Add-Routes

4. To start the SSM Agent service, run the following command:

   Start-Service AmazonSSMAgent

Additional troubleshooting steps

After you troubleshoot with the preceding steps, if the SSM Agent still fails to start, then take the following actions:

• To activate debug logging to capture detailed error information, modify the SSM Agent configuration file at C:\Program Files\Amazon\SSM\seelog.xml to set the log level to debug.
• Review your SSM Agent logs at %PROGRAMDATA%\Amazon\SSM\Logs\ for specific error messages that show the root cause.
• Confirm that you attached an IAM instance profile to the instance with the required Systems Manager permissions. For more information about required permissions, see Configure instance permissions required for Systems Manager.
• Make sure that your security group rules allow outbound traffic to Systems Manager endpoints on port 443.
• If you use virtual private cloud (VPC) endpoints for Systems Manager, then confirm that you properly configured the endpoints and associated them with the instance's subnet.

Related information

Troubleshooting managed node availability

Use instance metadata to manage your EC2 instance

How do I troubleshoot issues when I install or update SSM Agent on my Amazon EC2 Windows instance?

Why isn't Systems Manager showing my Amazon EC2 instance as a managed instance?