My Linux instances didn’t start successfully when I issued the instance start call. What should I look for when troubleshooting this?

When you issue the instance start call, AWS OpsWorks engages the following process:

1. OpsWorks builds instance user-data based on the OS type.

2. OpsWorks issues an EC2 RunInstances call, along with EC2 user-data.

3. OpsWorks creates a Setup lifecycle event.

4. During the instance boot, OpsWorks runs user-data and installs the opsworks-agent, downloaded from S3.
Note: For newer OS versions (Ubuntu 16.04 LTS, CentOS 7), Systemd manages the agent. Monit is used for monitoring and managing the agent on other supported OS versions.

5. After the instance is online and the agent is running, OpsWorks continuously checks for new commands and executes them.

6. The Setup lifecycle event is executed using Chef. When the Setup lifecycle event has completed, Chef logs are made available in the OpsWorks console and on the instance.

A failure at any of these points causes an instance to be in the start_failed state. To troubleshoot this, check the following:

1. Check the log file user-data.log at /var/log/aws/opsworks/ to find if the scripts in user-data of the instance have completed successfully.

2. Check installer.log to see if the OpsWorks agent installed successfully.
Note: The most common cause of failed agent installations is an incorrectly configured VPC. Make sure instances in your VPC can access the Internet; otherwise, the instance will attempt to download and install the agent, and the download will fail.

3. Make sure the agent is running.
For older OS versions:

$ ps -ef |grep opsworks-agent|wc -l


If the agent is not running on older OS versions, make sure monit is running by using the following command:

$ sudo service monit status

monit (pid 1769) is running...

For newer OS versions:

root@custsew2:/home/ubuntu# systemctl status opsworks-agent |grep Active

Active: active (running) since Tue 2016-06-28 17:47:03 UTC; 37s ago

If the agent is not running on the newer OS versions, inspect the journalctl logs.

4. If monit, which is responsible for monitoring and bringing up the agent, is not running, check /var/log/messages or /var/log/system.log.

5. If the agent is up and running and the instance is still in the start-failed state, check opsworks-agent.process_command.log to see if the agent has received the setup command to process it.

6. If the issue is still not clear, run the following AWS CLI command to see if there are any service errors that are causing the issue:

$ aws opsworks describe-service-errors --instance-id 63133710-806b-40e7-bbd1-8eb3ccd8c20b

instance start failure, start_failed, opsworks-agent not running, monit, systemd

Did this page help you? Yes | No

Back to the AWS Support Knowledge Center

Need help? Visit the AWS Support Center

Published: 2016-07-22