# Bootstrap failure error codes in Amazon EMR
<a name="emr-troubleshoot-error-errordetail-bootstrap"></a>

The following sections provide troubleshooting information for bootstrap failure error codes.

**Topics**
+ [

# BOOTSTRAP\$1FAILURE\$1PRIMARY\$1WITH\$1NON\$1ZERO\$1CODE
](BOOTSTRAP_FAILURE_PRIMARY_WITH_NON_ZERO_CODE.md)
+ [

# BOOTSTRAP\$1FAILURE\$1BA\$1DOWNLOAD\$1FAILED\$1PRIMARY
](BOOTSTRAP_FAILURE_BA_DOWNLOAD_FAILED_PRIMARY.md)
+ [

# BOOTSTRAP\$1FAILURE\$1FILE\$1NOT\$1FOUND\$1PRIMARY
](BOOTSTRAP_FAILURE_FILE_NOT_FOUND_PRIMARY.md)
+ [

# BOOTSTRAP\$1FAILURE\$1INSUFFICIENT\$1DISK\$1SPACE\$1PRIMARY
](BOOTSTRAP_FAILURE_INSUFFICIENT_DISK_SPACE_PRIMARY.md)
+ [

# BOOTSTRAP\$1FAILURE\$1INSUFFICIENT\$1DISK\$1SPACE\$1WORKER
](BOOTSTRAP_FAILURE_INSUFFICIENT_DISK_SPACE_WORKER.md)
+ [

# BOOTSTRAP\$1FAILURE\$1HIVE\$1METASTORE\$1CONNECTION\$1ERROR\$1PRIMARY
](BOOTSTRAP_FAILURE_HIVE_METASTORE_CONNECTION_ERROR_PRIMARY.md)
+ [

# BOOTSTRAP\$1FAILURE\$1HIVE\$1METASTORE\$1CONNECTION\$1ERROR\$1WORKER
](BOOTSTRAP_FAILURE_HIVE_METASTORE_CONNECTION_ERROR_WORKER.md)

# BOOTSTRAP\$1FAILURE\$1PRIMARY\$1WITH\$1NON\$1ZERO\$1CODE
<a name="BOOTSTRAP_FAILURE_PRIMARY_WITH_NON_ZERO_CODE"></a>

## Overview
<a name="BOOTSTRAP_FAILURE_BA_DOWNLOAD_FAILED_WITH_NON_ZERO_CODE_overview"></a>

When a cluster terminates with a `BOOTSTRAP_FAILURE_PRIMARY_WITH_NON_ZERO_CODE` error, a bootstrap action has failed in the primary instance. For more information about bootstrap actions, see [Create bootstrap actions to install additional software with an Amazon EMR cluster](emr-plan-bootstrap.md).

## Resolution
<a name="BOOTSTRAP_FAILURE_BA_DOWNLOAD_FAILED_WITH_NON_ZERO_CODE_resolution"></a>

To resolve this error, review the details returned in the API error, modify your bootstrap action script, and create a new cluster with the updated bootstrap action.

To troubleshoot the failed EMR cluster, refer to the `ErrorDetail` information returned from the `DescribeCluster` and `ListClusters` APIs. For more information, see [Error codes with ErrorDetail information in Amazon EMR](emr-troubleshoot-error-errordetail.md). The `ErrorData` array within `ErrorDetail` returns the following information for this error code:

**`primary-instance-id`**  
The ID of the primary instance where the bootstrap action failed.

**`bootstrap-action`**  
The ordinal number for the bootstrap action that failed. A script with a `bootstrap-action` value of `1` is the first bootstrap action to run on the instance.

**`return-code`**  
The return code for the bootstrap action that failed.

**`amazon-s3-path`**  
The Amazon S3 location of the bootstrap action that failed.

**`public-doc`**  
The public URL of the documentation for the error code.

## Steps to complete
<a name="BOOTSTRAP_FAILURE_BA_DOWNLOAD_FAILED_WITH_NON_ZERO_CODE_stc"></a>

Perform the following steps to identify and fix the root cause of the bootstrap action error. Then launch a new cluster.

1. Review the bootstrap action log files in Amazon S3 to identify the root cause for the failure. To learn more on how to view Amazon EMR logs, see [View Amazon EMR log files](emr-manage-view-web-log-files.md). 

1. If you turned on cluster logs when you created the instance, refer to the `stdout` log for more information. You can find the `stdout` log for the bootstrap action in this Amazon S3 location: 

   ```
   s3://amzn-s3-demo-bucket/logs/Your_Cluster_Id/node/Primary_Instance_Id/bootstrap-actions/Failed_Bootstrap_Action_Number/stdout.gz 
   ```

   For more information on cluster logs, see [Configure Amazon EMR cluster logging and debugging](emr-plan-debugging.md).

1. To determine the bootstrap action failure, review the exceptions in the `stdout` logs, and the `return-code` value in `ErrorData`.

1. Use your findings from the previous step to revise your bootstrap action so that it avoids exceptions or can gracefully handle exceptions when they occur.

1. Launch a new cluster with your updated bootstrap action.

# BOOTSTRAP\$1FAILURE\$1BA\$1DOWNLOAD\$1FAILED\$1PRIMARY
<a name="BOOTSTRAP_FAILURE_BA_DOWNLOAD_FAILED_PRIMARY"></a>

## Overview
<a name="BOOTSTRAP_FAILURE_BA_DOWNLOAD_FAILED_PRIMARY_overview"></a>

A cluster terminates with the `BOOTSTRAP_FAILURE_BA_DOWNLOAD_FAILED_PRIMARY` error when the primary instance can’t download a bootstrap action script from the Amazon S3 location that you specify. Potential causes include the following:
+ The bootstrap action script file isn’t in the specified Amazon S3 location.
+ The service role for Amazon EC2 instances on the cluster (also called the *EC2 instance profile for Amazon EMR*) doesn't have permissions to access the Amazon S3 bucket where the bootstrap action script resides. For more information about service roles, see [Service role for cluster EC2 instances (EC2 instance profile)](emr-iam-role-for-ec2.md).

For more information about bootstrap actions, see [Create bootstrap actions to install additional software with an Amazon EMR cluster](emr-plan-bootstrap.md).

## Resolution
<a name="BOOTSTRAP_FAILURE_BA_DOWNLOAD_FAILED_PRIMARY_resolution"></a>

To resolve this error, ensure that your primary instance has appropriate access to the bootstrap action script.

To troubleshoot the failed EMR cluster, refer to the `ErrorDetail` information returned from the `DescribeCluster` and `ListClusters` APIs. For more information, see [Error codes with ErrorDetail information in Amazon EMR](emr-troubleshoot-error-errordetail.md). The `ErrorData` array within `ErrorDetail` returns the following information for this error code:

**`primary-instance-id`**  
The ID of the primary instance where the bootstrap action failed.

**`bootstrap-action`**  
The ordinal number for the bootstrap action that failed. A script with a `bootstrap-action` value of `1` is the first bootstrap action to run on the instance.

**`amazon-s3-path`**  
The Amazon S3 location of the bootstrap action that failed.

**`public-doc`**  
The public URL of the documentation for the error code.

## Steps to complete
<a name="BOOTSTRAP_FAILURE_BA_DOWNLOAD_FAILED_PRIMARY_stc"></a>

Perform the following steps to identify and fix the root cause of the bootstrap action error. Then launch a new cluster.

**Troubleshooting steps**

1. Use the `amazon-s3-path` value from the `ErrorData` array to find the relevant bootstrap action script in Amazon S3.

1. If you turned on cluster logs when you created the instance, refer to the `stdout` log for more information. You can find the `stdout` log for the bootstrap action in this Amazon S3 location: 

   ```
   s3://amzn-s3-demo-bucket/logs/Your_Cluster_Id/node/Primary_Instance_Id/bootstrap-actions/Failed_Bootstrap_Action_Number/stdout.gz 
   ```

   For more information on cluster logs, see [Configure Amazon EMR cluster logging and debugging](emr-plan-debugging.md).

1. To determine the bootstrap action failure, review the exceptions in the `stdout` logs, and the `return-code` value in `ErrorData`.

1. Use your findings from the previous step to revise your bootstrap action so that it avoids exceptions or can gracefully handle exceptions when they occur.

1. Launch a new cluster with your updated bootstrap action.

# BOOTSTRAP\$1FAILURE\$1FILE\$1NOT\$1FOUND\$1PRIMARY
<a name="BOOTSTRAP_FAILURE_FILE_NOT_FOUND_PRIMARY"></a>

## Overview
<a name="BOOTSTRAP_FAILURE_FILE_NOT_FOUND_PRIMARY_overview"></a>

The `BOOTSTRAP_FAILURE_FILE_NOT_FOUND_PRIMARY` error indicates that the primary instance can’t find the bootstrap action script that the instance just downloaded from the specified Amazon S3 bucket.

## Resolution
<a name="BOOTSTRAP_FAILURE_FILE_NOT_FOUND_PRIMARY_resolution"></a>

To resolve this error, confirm that your primary instance has appropriate access to the bootstrap action script.

To troubleshoot the failed EMR cluster, refer to the `ErrorDetail` information returned from the `DescribeCluster` and `ListClusters` APIs. For more information, see [Error codes with ErrorDetail information in Amazon EMR](emr-troubleshoot-error-errordetail.md). The `ErrorData` array within `ErrorDetail` returns the following information for this error code:

**`primary-instance-id`**  
The ID of the primary instance where the bootstrap action failed.

**`bootstrap-action`**  
The ordinal number for the bootstrap action that failed. A script with a `bootstrap-action` value of `1` is the first bootstrap action to run on the instance.

**`amazon-s3-path`**  
The Amazon S3 location of the bootstrap action that failed.

**`public-doc`**  
The public URL of the documentation for the error code.

## Steps to complete
<a name="BOOTSTRAP_FAILURE_FILE_NOT_FOUND_PRIMARY_stc"></a>

Perform the following steps to identify and fix the root cause of the bootstrap action error. Then launch a new cluster.

1. To find the relevant bootstrap action script in Amazon S3, use the `amazon-s3-path` value from the `ErrorData` array.

1. Review the bootstrap action log files in Amazon S3 to identify the root cause for the failure. To learn more on how to view Amazon EMR logs, see [View Amazon EMR log files](emr-manage-view-web-log-files.md).
**Note**  
If you didn't turn on logs for your cluster, you must create a new cluster with the same configurations and bootstrap actions. To ensure the cluster logs are turned on, see [Configure Amazon EMR cluster logging and debugging](emr-plan-debugging.md).

1. Review the `stdout` log for your bootstrap actions and confirm that there are no custom processes that delete files in the `/emr/instance-controller/lib/bootstrap-actions` folder on your primary instances. You can find the `stdout` log for the bootstrap action in this Amazon S3 location: 

   ```
   s3://amzn-s3-demo-bucket/logs/Your_Cluster_Id/node/Primary_Instance_Id/bootstrap-actions/Failed_Bootstrap_Action_Number/stdout.gz
   ```

1. Launch a new cluster with your updated bootstrap action.

# BOOTSTRAP\$1FAILURE\$1INSUFFICIENT\$1DISK\$1SPACE\$1PRIMARY
<a name="BOOTSTRAP_FAILURE_INSUFFICIENT_DISK_SPACE_PRIMARY"></a>

## Overview
<a name="BOOTSTRAP_FAILURE_INSUFFICIENT_DISK_SPACE_PRIMARY_overview"></a>

 The `BOOTSTRAP_FAILURE_INSUFFICIENT_DISK_SPACE_PRIMARY` error indicates that the primary instance does not have enough disk space when installing necessary software. 

## Resolution
<a name="BOOTSTRAP_FAILURE_INSUFFICIENT_DISK_SPACE_PRIMARY_resolution"></a>

 To resolve this error, confirm that your primary instance has sufficient disk space on the root volume. 

To troubleshoot the failed EMR cluster, refer to the `ErrorDetail` information returned from the `DescribeCluster` and `ListClusters` APIs. For more information, see [Error codes with ErrorDetail information in Amazon EMR](emr-troubleshoot-error-errordetail.md). The `ErrorData` array within `ErrorDetail` returns the following information for this error code:

**`primary-instance-id`**  
The ID of the primary instance with insufficient disk space.

**`public-doc`**  
The public URL of the documentation for the error code.

## Steps to complete
<a name="BOOTSTRAP_FAILURE_INSUFFICIENT_DISK_SPACE_PRIMARY_stc"></a>

1.  Review the best practices for your cluster’s EBS root device volume. See [Customizing the Amazon EBS root device volume](emr-custom-ami-root-volume-size.md) in the *Amazon EMR Management Guide*. 

1. Launch a new cluster with a larger EBS root device volume size.

# BOOTSTRAP\$1FAILURE\$1INSUFFICIENT\$1DISK\$1SPACE\$1WORKER
<a name="BOOTSTRAP_FAILURE_INSUFFICIENT_DISK_SPACE_WORKER"></a>

## Overview
<a name="BOOTSTRAP_FAILURE_INSUFFICIENT_DISK_SPACE_WORKER_overview"></a>

 The `BOOTSTRAP_FAILURE_INSUFFICIENT_DISK_SPACE_WORKER` error indicates that one or more worker instances do not have enough disk space when installing necessary software. 

## Resolution
<a name="BOOTSTRAP_FAILURE_INSUFFICIENT_DISK_SPACE_WORKER_resolution"></a>

 To resolve this error, confirm that your worker instances have sufficient disk space on the root volume. 

To troubleshoot the failed EMR cluster, refer to the `ErrorDetail` information returned from the `DescribeCluster` and `ListClusters` APIs. For more information, see [Error codes with ErrorDetail information in Amazon EMR](emr-troubleshoot-error-errordetail.md). The `ErrorData` array within `ErrorDetail` returns the following information for this error code:

**`worker-instance-ids`**  
The IDs of the worker instances with insufficient disk space.

**`public-doc`**  
The public URL of the documentation for the error code.

## Steps to complete
<a name="BOOTSTRAP_FAILURE_INSUFFICIENT_DISK_SPACE_WORKER_stc"></a>

1.  Review the best practices for your cluster’s EBS root device volume. See [Customizing the Amazon EBS root device volume](emr-custom-ami-root-volume-size.md) in the *Amazon EMR Management Guide*. 

1. Launch a new cluster with a larger EBS root device volume size.

# BOOTSTRAP\$1FAILURE\$1HIVE\$1METASTORE\$1CONNECTION\$1ERROR\$1PRIMARY
<a name="BOOTSTRAP_FAILURE_HIVE_METASTORE_CONNECTION_ERROR_PRIMARY"></a>

## Overview
<a name="BOOTSTRAP_FAILURE_HIVE_METASTORE_CONNECTION_ERROR_PRIMARY_overview"></a>

 The `BOOTSTRAP_FAILURE_HIVE_METASTORE_CONNECTION_ERROR_PRIMARY` error indicates that the primary instance is unable to establish a connection to the configured external Hive Metastore. 

## Resolution
<a name="BOOTSTRAP_FAILURE_HIVE_METASTORE_CONNECTION_ERROR_PRIMARY_resolution"></a>

 To resolve this error, confirm that your external Hive Metastore is configured properly and the primary instance is allowed to connect to it. 

To troubleshoot the failed EMR cluster, refer to the `ErrorDetail` information returned from the `DescribeCluster` and `ListClusters` APIs. For more information, see [Error codes with ErrorDetail information in Amazon EMR](emr-troubleshoot-error-errordetail.md). The `ErrorData` array within `ErrorDetail` returns the following information for this error code:

**`primary-instance-id`**  
The ID of the primary instance unable to establish a connection to the configured external Hive Metastore.

**`public-doc`**  
The public URL of the documentation for the error code.

## Steps to complete
<a name="BOOTSTRAP_FAILURE_HIVE_METASTORE_CONNECTION_ERROR_PRIMARY_stc"></a>

1.  Review the best practices for for configuring an external metastore for Hive. See [Configuring an external metastore for Hive](https://docs.aws.amazon.com/emr/latest/ReleaseGuide/emr-metastore-external-hive.html). 

1. Launch a new cluster with your updated cluster configuration.

# BOOTSTRAP\$1FAILURE\$1HIVE\$1METASTORE\$1CONNECTION\$1ERROR\$1WORKER
<a name="BOOTSTRAP_FAILURE_HIVE_METASTORE_CONNECTION_ERROR_WORKER"></a>

## Overview
<a name="BOOTSTRAP_FAILURE_HIVE_METASTORE_CONNECTION_ERROR_WORKER_overview"></a>

 The `BOOTSTRAP_FAILURE_HIVE_METASTORE_CONNECTION_ERROR_WORKER` error indicates that one or more worker instances are unable to establish a connection to the configured external Hive Metastore. 

## Resolution
<a name="BOOTSTRAP_FAILURE_HIVE_METASTORE_CONNECTION_ERROR_WORKER_resolution"></a>

 To resolve this error, confirm that your external Hive Metastore is configured properly and the worker instances are allowed to connect to it. 

To troubleshoot the failed EMR cluster, refer to the `ErrorDetail` information returned from the `DescribeCluster` and `ListClusters` APIs. For more information, see [Error codes with ErrorDetail information in Amazon EMR](emr-troubleshoot-error-errordetail.md). The `ErrorData` array within `ErrorDetail` returns the following information for this error code:

**`worker-instance-ids`**  
The IDs of the worker instances unable to establish a connection to the configured external Hive Metastore.

**`public-doc`**  
The public URL of the documentation for the error code.

## Steps to complete
<a name="BOOTSTRAP_FAILURE_HIVE_METASTORE_CONNECTION_ERROR_WORKER_stc"></a>

1.  Review the best practices for for configuring an external metastore for Hive. See [Configuring an external metastore for Hive](https://docs.aws.amazon.com/emr/latest/ReleaseGuide/emr-metastore-external-hive.html). 

1. Launch a new cluster with your updated cluster configuration.