Detailed deployment error codes
Use the error codes and solutions in these sections to help resolve issues with component deployment when using the Greengrass nucleus version 2.8.0 or later.
The Greengrass nucleus reports deployment errors as a hierarchy from least specific to the most specific code available. You can use this hierarchy to help pinpoint the reason for a deployment error. For example, the following is a possible error hierarchy:
-
DEPLOYMENT_FAILURE
-
ARTIFACT_DOWNLOAD_ERROR
-
IO_ERROR
-
DISK_SPACE_CRITICAL
-
-
-
The error codes are organized into types. Each type represents a class of errors that can
occur. AWS IoT Greengrass reports these errors types in the console, the API, and AWS CLI. There can be more than
one error type, depending on the errors reported in the error hierarchy. For the preceding
example, the error type returned is DEVICE_ERROR
.
The types are:
-
PERMISSION_ERROR – Access to an operation that requires permission was denied.
-
REQUEST_ERROR – An error occurred due to an issue in the deployment document.
-
COMPONENT_RECIPE_ERROR – An error occurred due to an issue in a component recipe.
-
AWS_COMPONENT_ERROR – An error occurred when starting or removing an AWS provided component.
-
USER_COMPONENT_ERROR – An error occurred when starting or removing a user component.
-
COMPONENT_ERROR – An error occurred when starting or removing a component, but the Greengrass nucleus couldn't determine if the component is an AWS provided component or a user component.
-
DEVICE_ERROR – An error occurred with local I/O or another device error occurred.
-
DEPENDENCY_ERROR – A deployment failed to download an artifact from Amazon S3 or to pull an image from an ECR registry.
-
HTTP_ERROR – An error occurred with an HTTP request.
-
NETWORK_ERROR – An error occurred with the device network.
-
NUCLEUS_ERROR – The Greengrass nucleus could not locate a component or could not find the active nucleus version.
-
SERVER_ERROR – A server returned a 500 error in response to a request.
-
CLOUD_SERVICE_ERROR – An error occurred with the AWS IoT Greengrass cloud service.
-
UNKNOWN_ERROR – An unchecked exception was thrown by the component.
Many of the errors in this section report additional information in the AWS IoT Greengrass Core logs. These logs are stored on the core device's local file system. There are logs for the AWS IoT Greengrass Core core software and for each individual component. For information on accessing the logs, see Access file system logs.
Permission error
- ACCESS_DENIED
-
You might get this error when an AWS service operation returns a 403 error because permissions are not set up correctly. Check the more specific error code for details.
- GET_DEPLOYMENT_CONFIGURATION_ACCESS_DENIED
-
You might get this error when the AWS IoT policy doesn't allow permission to call the
GetDeploymentConfiguration
operation. Add thegreengrass::GetDeploymentConfiguration
permission to the core device's policy. - GET_COMPONENT_VERSION_ARTIFACT_ACCESS_DENIED
-
You might get this error when the core device AWS IoT policy doesn't allow the
greengrass:GetComponentVersionArtifact
permission. Add the permission to the core device's policy. - RESOLVE_COMPONENT_CANDIDATES_ACCESS_DENIED
-
You might get this error when the core device AWS IoT policy doesn't allow the
greengrass:ResolveComponentCandidates
permission. Add the permission to the core device's policy. - GET_ECR_CREDENTIAL_ERROR
-
You might get this error when the deployment couldn't authenticate with a private registry in ECR. Check the log for a specific error and then try the deployment again.
- USER_NOT_AUTHORIZED_FOR_DOCKER
-
You might get this error when the Greengrass user is not authorized to use Docker. Make sure that you are running Greengrass as root or that the user is added to the
docker
group. Then try the deployment again. - S3_ACCESS_DENIED
-
You might get this error when an Amazon S3 operation returns a 403 error. Check any additional error codes or logs for details.
- S3_HEAD_OBJECT_ACCESS_DENIED
-
You might get this error either when the device's token exchange role doesn't allow the AWS IoT Greengrass Core software to download the component artifact from the S3 object URL that you specify in the component's recipe or that the component artifact isn't available. Check that the token exchange role allows
s3:GetObject
for the S3 object URL where the artifact is available and that the artifact is present. - S3_GET_BUCKET_LOCATION_ACCESS_DENIED
-
You might get this error when the device's token exchange role doesn't allow the
s3:GetBucketLocation
permission for the Amazon S3 bucket where the artifact is available. Check that the device's allows the permission then try the deployment again. - S3_GET_OBJECT_ACCESS_DENIED
-
You might get this error either when the device's token exchange role doesn't allow the AWS IoT Greengrass Core software to download the component artifact from the S3 object URL that you specify in the component's recipe or that the component artifact isn't available. Check that the token exchange role allows
s3:GetObject
for the S3 object URL where the artifact is available and that the artifact is present.
Request error
- NUCLEUS_MISSING_REQUIRED_CAPABILITIES
-
You might get this error when the nucleus version in the deployment isn't capable a requested operation, such as downloading a large configuration or setting Linux resource limits. Retry the deployment with a nucleus version that supports the operation.
- MULTIPLE_NUCLEUS_RESOLVED_ERROR
-
You might get this error when a deployment attempts to deploy multiple nucleus components. Check the log to see what caused the error, then check the nucleus software update page to see if the issue has been corrected in a later version of the nucleus, or contact AWS Support.
- COMPONENT_CIRCULAR_DEPENDENCY_ERROR
-
You might get this error when two components in your deployment depend on each other. Revise the component setup so that the components in your deployment don't rely on each other.
- UNAUTHORIZED_NUCLEUS_MINOR_VERSION_UPDATE
-
You might get this error when a component in your deployment requires a nucleus minor version update, but that version isn't specified in the deployment. This helps to reduce accidental minor version updates for components that depend on a different version. Include the new minor nucleus version in the deployment.
- MISSING_DOCKER_APPLICATION_MANAGER
-
You might get this error when you deploy a Docker component without deploying the Docker application manager. Make sure that your deployment includes the Docker application manager.
- MISSING_TOKEN_EXCHANGE_SERVICE
-
You might get this error when the deployment wants to download a Docker image artifact from a private ECR registry without deploying the token exchange service. Make sure that your deployment includes the token exchange service.
- COMPONENT_VERSION_REQUIREMENTS_NOT_MET
-
You might get this error when there is a version constraint conflict or a component version does not exist. For more information, see Error: com.aws.greengrass.componentmanager.exceptions.NoAvailableComponentVersionException: Failed to negotiate component <name> version with cloud and no local applicable version satisfying requirement <requirements>.
- THROTTLING_ERROR
-
You might get this error when an AWS service operation exceeded a rate quota. Retry the deployment.
- CONFLICTED_REQUEST
-
You might get this error when an AWS service operation returns a 409 error because you deployment is trying to perform more than one operation at a time. Retry the deployment.
- RESOURCE_NOT_FOUND
-
You might get this error when an AWS service operation returns a 404 error because a resource couldn't be found. Check the log for the missing resource.
- RUN_WITH_CONFIG_NOT_VALID
-
You might get this error when the
posixUser
,posixGroup
, orwindowsUser
information specified to run the component isn't valid. Check that the user is valid and then retry the deployment. - UNSUPPORTED_REGION
-
You might get this error when the Region specified for the deployment isn't supported by AWS IoT Greengrass. Check the Region and try the deployment again.
- IOT_CRED_ENDPOINT_NOT_VALID
-
You might get this error when the AWS IoT credential endpoint specified in the configuration isn't valid. Check the endpoint and try your request again.
- IOT_DATA_ENDPOINT_NOT_VALID
-
You might get this error when the AWS IoT data endpoint specified in the configuration isn't valid. Check the endpoint and try your request again.
- S3_HEAD_OBJECT_RESOURCE_NOT_FOUND
-
You might get this error when the component artifact isn't available at the S3 object URL that you specify in the component's recipe. Check that you uploaded the artifact to the S3 bucket and that the artifact URI matches the S3 object URL of the artifact in the bucket.
- S3_GET_BUCKET_LOCATION_RESOURCE_NOT_FOUND
-
You might get this error when the Amazon S3 bucket isn't found. Check that the bucket exists and try the deployment again.
- S3_GET_OBJECT_RESOURCE_NOT_FOUND
-
You might get this error when the component artifact isn't available at the S3 object URL that you specify in the component's recipe. Check that you uploaded the artifact to the S3 bucket and that the artifact URI matches the S3 object URL of the artifact in the bucket.
- IO_MAPPING_ERROR
-
You might get this error when an I/O error occurs when parsing deployment document or recipe. Check any additional error codes or logs for details.
Component recipe error
- RECIPE_PARSE_ERROR
-
You might get this error when the deployment recipe couldn't be parsed because there is an error in the structure of the recipe. Check that the recipe is correctly formatted and try the deployment again.
- RECIPE_METADATA_PARSE_ERROR
-
You might get this error when the deployment recipe metadata downloaded from the cloud couldn't be parsed. Contact AWS Support.
- ARTIFACT_URI_NOT_VALID
-
You might get this error when an artifact URI in a recipe isn't formatted correctly. Check the log for the URI that isn't valid, update the URI in the recipe, then try the deployment again.
- S3_ARTIFACT_URI_NOT_VALID
-
You might get this error when the Amazon S3 URI of an artifact in a recipe isn't valid. Check the log for the URI that isn't valid, update the URI in the recipe, then try the deployment again.
- DOCKER_ARTIFACT_URI_NOT_VALID
-
You might get this error when the Docker URI of an artifact in a recipe isn't valid. Check the log for the URI that isn't valid, update the URI in the recipe, then try the deployment again.
- EMPTY_ARTIFACT_URI
-
You might get this error when the URI of an artifact is not specified in a recipe. Check the log for the artifact that is missing a URI, update the URI in the recipe, then try the deployment again.
- EMPTY_ARTIFACT_SCHEME
-
You might get this error when a URI scheme is not defined for an artifact. Check the log for the URI that isn't valid, update the URI in the recipe, then try the deployment again.
- UNSUPPORTED_ARTIFACT_SCHEME
-
You might get this error when a URI scheme isn't supported by the running nucleus version. Either a URI isn't valid or you need to update the nucleus version. If the URI isn't valid, check the log for the URI that isn't valid, update the URI in the recipe, then try the deployment again.
- RECIPE_MISSING_MANIFEST
-
You might get this error when the manifest section isn't included in the recipe. Add the manifest to the recipe and try the deployment again.
- RECIPE_MISSING_ARTIFACT_HASH_ALGORITHM
-
You might get this error when an artifact that is not local is specified inside a recipe without a hash algorithm. Add the algorithm to the artifact and then try the request again.
- ARTIFACT_CHECKSUM_MISMATCH
-
You might get this error when a downloaded artifact has a different digest than the one specified in the recipe. Make sure that the recipe contains the correct digest and then try the deployment again. For more information see Error: com.aws.greengrass.componentmanager.exceptions.ArtifactChecksumMismatchException: Integrity check for downloaded artifact failed. Probably due to file corruption..
- COMPONENT_DEPENDENCY_NOT_VALID
-
You might get this error when the dependency type specified in a deployment recipe isn't valid. Check the recipe and then try your request again.
- CONFIG_INTERPOLATE_ERROR
-
You might get this error when interpolating a recipe variable. Check the log for details.
- IO_MAPPING_ERROR
-
You might get this error when an I/O error occurs when parsing deployment document or recipe. Check any additional error codes or logs for details.
AWS component error, user component error, component error
The following error codes are returned when there is a problem with a component. The actual
error type reported depends on the specific component that raised the error. If the Greengrass nucleus
identifies the component as one provided by AWS IoT Greengrass, it returns AWS_COMPONENT_ERROR
. If
the component is identified as a user component, the Greengrass nucleus returns
USER_COMPONENT_ERROR
. If the Greengrass nucleus can't tell, it returns
COMPONENT_ERROR
.
- COMPONENT_UPDATE_ERROR
-
You might get this error when a component doesn't update during a deployment. Check any additional error codes or check the log to see what caused the error.
- COMPONENT_BROKEN
-
You might get this error when a component is broken during a deployment. Check the component log for error details and then try the deployment again.
- REMOVE_COMPONENT_ERROR
-
You might get this error when the nucleus can't remove a component during a deployment. Check the log for error details and then try the deployment again.
- COMPONENT_BOOTSTRAP_TIMEOUT
-
You might get this error when a component's bootstrap task took longer than the configured timeout. Increase the timeout or reduce the execution time of the bootstrap task, then try the deployment again.
- COMPONENT_BOOTSTRAP_ERROR
-
You might get this error when a component's bootstrap task has an error. Check the log for error details, then try the deployment again.
- COMPONENT_CONFIGURATION_NOT_VALID
-
You might get this error when the nucleus can't validate the deployed configuration for the component. Check the log for error details, then try the deployment again.
Device error
- IO_WRITE_ERROR
-
You might get this error when writing to a file. Check the log for details.
- IO_READ_ERROR
-
You might get this error when reading from a file. Check the log for details.
- DISK_SPACE_CRITICAL
-
You might get this error when there is not enough disk space to complete a deployment request. You must have at least 20 Mb of available space, or enough to hold a larger artifact. Free up some disk space and then retry the deployment.
- IO_FILE_ATTRIBUTE_ERROR
-
You might get this error when the existing file size can't be retrieved from the file system. Check the log for details.
- SET_PERMISSION_ERROR
-
You might get this error when the permissions can't be set on a downloaded artifact or artifact directory. Check the log for details.
- IO_UNZIP_ERROR
-
You might get this error when an artifact can't be unzipped. Check the log for details.
- LOCAL_RECIPE_NOT_FOUND
-
You might get this error when the local copy of a recipe file couldn't be found. Try the deployment again.
- LOCAL_RECIPE_CORRUPTED
-
You might get this error when the local copy of the recipe has changed since it was downloaded. Delete the existing copy of the recipe and try the deployment again.
- LOCAL_RECIPE_METADATA_NOT_FOUND
-
You might get this error when the local copy of the recipe metadata file couldn't be found. Try the deployment again.
- LAUNCH_DIRECTORY_CORRUPTED
-
You might get this error when the directory used to launch the Greengrass nucleus (
/greengrass/v2/alts/current
) has been modified since the last time the nucleus was started. Restart the nucleus and then retry the deployment. - HASHING_ALGORITHM_UNAVAILABLE
-
You might get this error when the device's Java distribution doesn't support the required hashing algorithm or when the hash algorithm specified in a component recipe isn't valid.
- DEVICE_CONFIG_NOT_VALID_FOR_ARTIFACT_DOWNLOAD
-
You might get this error when there is an error in the device configuration that prevented the deployment from downloading the artifact from Amazon S3 or the Greengrass cloud. Check the log for a specific configuration error and then retry the deployment.
Dependency error
- DOCKER_ERROR
-
You might get this error when pulling a Docker image. Check any additional error codes or logs for details.
- DOCKER_SERVICE_UNAVAILABLE
-
You might get this error when Greengrass couldn't log into the Docker registry. Check the log for a specific error and then try the deployment again.
- DOCKER_LOGIN_ERROR
-
You might get this error when an unexpected error occurs when logging in to Docker. Check the log for a specific error and then try the deployment again.
- DOCKER_PULL_ERROR
-
You might get this error when an unexpected error occurs when pulling a Docker image from the registry. Check the log for a specific error and then try the deployment again.
- DOCKER_IMAGE_NOT_VALID
-
You might get this error when the requested Docker image doesn't exist. Check the log for a specific error and try the deployment again.
- DOCKER_IMAGE_QUERY_ERROR
-
You might get this error when an unexpected failure occurs when querying Docker for available images. Check the log for the specific error and try the deployment again.
- S3_ERROR
-
You might get this error when downloading an Amazon S3 artifact. Check any additional error codes or logs for details.
- S3_RESOURCE_NOT_FOUND
-
You might get this error when an Amazon S3 operation returns a 404 error. Check any additional error codes or logs for details.
- S3_BAD_REQUEST
-
You might get this error when an Amazon S3 operation returns a 400 error. Check the log for a specific error and try the request again.
HTTP error
- HTTP_REQUEST_ERROR
-
You might get this error when an error occurred when making an HTTP request. Check the log for the specific error.
- DOWNLOAD_DEPLOYMENT_DOCUMENT_ERROR
-
You might get this error when an HTTP error occurred when downloading the deployment document. Check the log for the specific HTTP error.
- GET_GREENGRASS_ARTIFACT_SIZE_ERROR
-
You might get this error when an HTTP error occurred when getting the size of a public component artifact. Check the log for the specific HTTP error.
- DOWNLOAD_GREENGRASS_ARTIFACT_ERROR
-
You might get this error when an HTTP error occurred when downloading a public component artifact. Check the log for the specific HTTP error.
Network error
- NETWORK_ERROR
-
You might get this error when there is a connection issue during a deployment. Check the connection of the device to the Internet and try the deployment again.
Nucleus error
- BAD_REQUEST
-
You might get this error when an AWS cloud operation returns a 400 error. Check the log to see which API caused the error, then check the nucleus software update page to see if the issue has been corrected in a later version of the nucleus, or contact AWS Support.
- NUCLEUS_VERSION_NOT_FOUND
-
You might get this error when a core device can't find the version of the active nucleus. Check the log to see what caused the error, then check the nucleus software update page to see if the issue has been corrected in a later version of the nucleus, or contact AWS Support.
- NUCLEUS_RESTART_FAILURE
-
You might get this error when the nucleus doesn't restart during any deployment that requires a nucleus restart. Check the loader log to see what caused the error, then check the nucleus software update page to see if the issue has been corrected in a later version of the nucleus, or contact AWS Support.
- INSTALLED_COMPONENT_NOT_FOUND
-
You might get this error when the nucleus can't locate an installed component. Check the log to see what caused the error, then check the nucleus software update page to see if the issue has been corrected in a later version of the nucleus, or contact AWS Support.
- DEPLOYMENT_DOCUMENT_NOT_VALID
-
You might get this error when the device receives deployment document that isn't valid. Check any additional error codes or check the log to see what caused the error.
- EMPTY_DEPLOYMENT_REQUEST
-
You might get this error when a device receives an empty deployment request. Check the log to see what caused the error, then check the nucleus software update page to see if the issue has been corrected in a later version of the nucleus, or contact AWS Support.
- DEPLOYMENT_DOCUMENT_PARSE_ERROR
-
You might get this error when the deployment request format doesn't match the expected format. Check the log to see what caused the error, then check the nucleus software update page to see if the issue has been corrected in a later version of the nucleus, or contact AWS Support.
- COMPONENT_METADATA_NOT_VALID_IN_DEPLOYMENT
-
You might get this error when the deployment request contains component metadata that isn't valid. Check the log to see what caused the error, then check the nucleus software update page to see if the issue has been corrected in a later version of the nucleus, or contact AWS Support.
- LAUNCH_DIRECTORY_CORRUPTED
-
You might get this error when you move a Greengrass device from one thing group to another, and then back to the original group with deployments that require Greengrass to restart. To resolve the error, recreate the launch directory for Greengrass on the device.
For more information, see Error: com.aws.greengrass.deployment.exceptions.DeploymentException: Unable to process deployment. Greengrass launch directory is not set up or Greengrass is not set up as a system service.
Server error
- SERVER_ERROR
-
You might get this error when an AWS service operation returns a 500 error because the service can't process the request right now. Retry the deployment later.
- S3_SERVER_ERROR
-
You might get this error when an Amazon S3 operation returns a 500 error. Check any additional error codes or logs for details.
Cloud service error
- RESOLVE_COMPONENT_CANDIDATES_BAD_RESPONSE
-
You might get this error when the Greengrass cloud service sends an incompatible response to the
ResolveComponentCandidates
operation. Check the log to see what caused the error, then check the nucleus software update page to see if the issue has been corrected in a later version of the nucleus, or contact AWS Support. - DEPLOYMENT_DOCUMENT_SIZE_EXCEEDED
-
You might get this error when the requested deployment document exceeded the maximum size quota. Reduce the size of the deployment document and try the deployment again.
- GREENGRASS_ARTIFACT_SIZE_NOT_FOUND
-
You might get this error when Greengrass can't get the size of a public component artifact. Check the log to see what caused the error, then check the nucleus software update page to see if the issue has been corrected in a later version of the nucleus, or contact AWS Support.
- DEPLOYMENT_DOCUMENT_NOT_VALID
-
You might get this error when the device receives deployment document that isn't valid. Check any additional error codes or check the log to see what caused the error.
- EMPTY_DEPLOYMENT_REQUEST
-
You might get this error when a device receives an empty deployment request. Check the log to see what caused the error, then check the nucleus software update page to see if the issue has been corrected in a later version of the nucleus, or contact AWS Support.
- DEPLOYMENT_DOCUMENT_PARSE_ERROR
-
You might get this error when the deployment request format doesn't match the expected format. Check the log to see what caused the error, then check the nucleus software update page to see if the issue has been corrected in a later version of the nucleus, or contact AWS Support.
- COMPONENT_METADATA_NOT_VALID_IN_DEPLOYMENT
-
You might get this error when the deployment request contains component metadata that isn't valid. Check the log to see what caused the error, then check the nucleus software update page to see if the issue has been corrected in a later version of the nucleus, or contact AWS Support.
Generic errors
These generic errors do not have an associated error type.
- DEPLOYMENT_INTERRUPTED
-
You might get this error when a deployment can't be completed because of a nucleus shutdown or other external event. Check any additional error codes or logs for details.
- ARTIFACT_DOWNLOAD_ERROR
-
You might get this error when there is a problem downloading an artifact. Check any additional error codes or logs for details.
- NO_AVAILABLE_COMPONENT_VERSION
-
You might get this error when a component version doesn't exist in the cloud or locally, or if there is a dependency resolution conflict. Check any additional error codes or logs for details.
- COMPONENT_PACKAGE_LOADING_ERROR
-
You might get this error when an error processing the downloaded artifacts. Check any additional error codes or logs for details.
- CLOUD_API_ERROR
-
You might get this error when an error occurred calling an AWS service API. Check any additional error codes or logs for details.
- IO_ERROR
-
You might get this error when an I/O error occurs during a deployment. Check any additional error codes or logs for details.
- COMPONENT_UPDATE_ERROR
-
You might get this error when a component doesn't update during a deployment. Check any additional error codes or check the log to see what caused the error.
Unknown error
- DEPLOYMENT_FAILURE
-
You might get this error when a deployment fails because an unchecked exception was thrown. Check the log to see what caused the error, then check the nucleus software update page to see if the issue has been corrected in a later version of the nucleus, or contact AWS Support.
- DEPLOYMENT_TYPE_NOT_VALID
-
You might get this error when the deployment type isn't valid. Check the log to see what caused the error, then check the nucleus software update page to see if the issue has been corrected in a later version of the nucleus, or contact AWS Support.