Menu
AWS CodeBuild
User Guide (API Version 2016-10-06)

Troubleshooting AWS CodeBuild

Use the information in this topic to help you identify, diagnose, and address issues.

Error: "CodeBuild is not authorized to perform: sts:AssumeRole" When Creating or Updating a Build Project

Issue: When you try to create or update a build project, you receive the following error: "Code:InvalidInputException, Message:CodeBuild is not authorized to perform: sts:AssumeRole on arn:aws:iam::account-ID:role/service-role-name".

Possible causes:

  • The AWS Security Token Service (AWS STS) has been deactivated for the AWS region where you are attempting to create or update the build project.

  • The AWS CodeBuild service role associated with the build project does not exist or does not have sufficient permissions to trust AWS CodeBuild.

Recommended solutions:

  • Make sure AWS STS is activated for the AWS region where you are attempting to create or update the build project. For more information, see Activating and Deactivating AWS STS in an AWS Region in the IAM User Guide.

  • Make sure the target AWS CodeBuild service role exists in your AWS account. If you are not using the console, make sure you did not misspell the Amazon Resource Name (ARN) of the service role when you created or updated the build project.

  • Make sure the target AWS CodeBuild service role has sufficient permissions to trust AWS CodeBuild. For more information, see the trust relationship policy statement in Create an AWS CodeBuild Service Role.

Error: "The bucket you are attempting to access must be addressed using the specified endpoint..." When Running a Build

Issue: When you run a build, the DOWNLOAD_SOURCE build phase fails with the error "The bucket you are attempting to access must be addressed using the specified endpoint. Please send all future requests to this endpoint."

Possible cause: Your pre-built source code is stored in an Amazon S3 bucket, and that bucket is in a different AWS region than the AWS CodeBuild build project.

Recommended solution: Update the build project's settings to point to a bucket that contains your pre-built source code, and that bucket is in the same region as the build project.

Error: "Failed to upload artifacts: Invalid arn" When Running a Build

Issue: When you run a build, the UPLOAD_ARTIFACTS build phase fails with the error "Failed to upload artifacts: Invalid arn".

Possible cause: Your Amazon S3 output bucket (the bucket where AWS CodeBuild stores its output from the build) is in a different AWS region than the AWS CodeBuild build project.

Recommended solution: Update the build project's settings to point to an output bucket that is in the same region as the build project.

Error: "Unable to Locate Credentials"

Issue: When you try to run the AWS CLI, use an AWS SDK, or call another similar component as part of a build, you get build errors that are directly related to the AWS CLI, AWS SDK, or component. For example, you may get a build error such as "unable to locate credentials."

Possible causes:

  • The version of the AWS CLI, AWS SDK, or component in the build environment is incompatible with AWS CodeBuild.

  • You are running a Docker container within a build environment that uses Docker, and that Docker container does not have access to the necessary AWS credentials by default.

Recommended solutions:

  • Make sure your build environment has the following version or higher of the AWS CLI, AWS SDK, or component.

    • AWS CLI: 1.10.47

    • AWS SDK for C++: 0.2.19

    • AWS SDK for Go: 1.2.5

    • AWS SDK for Java: 1.11.16

    • AWS SDK for JavaScript: 2.4.7

    • AWS SDK for PHP: 3.18.28

    • AWS SDK for Python (Boto3): 1.4.0

    • AWS SDK for Ruby: 2.3.22

    • Botocore: 1.4.37

    • CoreCLR: 3.2.6-beta

    • Node.js: 2.4.7

  • If you need to run a Docker container in a build environment and that container requires AWS credentials, you must pass through the credentials from the build environment to the container. In your build spec, include a Docker run command such as the following, which in this example uses the aws s3 ls command to list your available Amazon S3 buckets. The -e option passes through the necessary environment variables for your container to access AWS credentials.

    Copy
    docker run -e AWS_DEFAULT_REGION -e AWS_CONTAINER_CREDENTIALS_RELATIVE_URI your-image-tag aws s3 ls
  • If you are building a Docker image and the build requires AWS credentials (for example, to download a file from Amazon S3), you must pass through the credentials from the build environment to the Docker build process as follows.

    1. In your source code's Dockerfile for the Docker image, specify the following ARG instructions.

      Copy
      ARG AWS_DEFAULT_REGION ARG AWS_CONTAINER_CREDENTIALS_RELATIVE_URI
    2. In your build spec, include a Docker build command such as the following. The --build-arg options will set the necessary environment variables for your Docker build process to access the AWS credentials.

      Copy
      docker build --build-arg AWS_DEFAULT_REGION=$AWS_DEFAULT_REGION --build-arg AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=$AWS_CONTAINER_CREDENTIALS_RELATIVE_URI -t your-image-tag .

Earlier Commands in Build Specs Are Not Recognized by Later Commands

Issue: The results of one or more commands in your build spec are not recognized by later commands in the same build spec. For example, a command might set a local environment variable, but a command run later might fail to get the value of that local environment variable.

Possible cause: In build spec version 0.1, AWS CodeBuild runs each command in a separate instance of the default shell in the build environment. This means that each command runs in isolation from all other commands. By default, then, you cannot run a single command that relies on the state of any previous commands.

Recommended solutions: We recommend you use build spec version 0.2, which solves this issue. If you must use build spec version 0.1 for some reason, we recommend using the shell command chaining operator (for example, && in Linux) to combine multiple commands into a single command. Or include a shell script in your source code that contains multiple commands, and then call that shell script from a single command in the build spec. For more information, see Shells and Commands in Build Environments and Environment Variables in Build Environments.

Apache Maven Builds Reference Artifacts from the Wrong Repository

Issue: When you use Maven with an AWS CodeBuild provided Java build environment, Maven pulls build and plugin dependencies from the secure central Maven repository at https://repo1.maven.org/maven2. This happens even if your build project's pom.xml file explicitly declares other locations to use instead.

Possible cause: AWS CodeBuild provided Java build environments include a file named settings.xml that is preinstalled in the build environment's /root/.m2 directory. This settings.xml file contains the following declarations, which instruct Maven to always pull build and plugin dependencies from the secure central Maven repository at https://repo1.maven.org/maven2.

Copy
<settings> <activeProfiles> <activeProfile>securecentral</activeProfile> </activeProfiles> <profiles> <profile> <id>securecentral</id> <repositories> <repository> <id>central</id> <url>https://repo1.maven.org/maven2</url> <releases> <enabled>true</enabled> </releases> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>central</id> <url>https://repo1.maven.org/maven2</url> <releases> <enabled>true</enabled> </releases> </pluginRepository> </pluginRepositories> </profile> </profiles> </settings>

Recommended solution: Do the following:

  1. Add a settings.xml file to your source code.

  2. In this settings.xml file, use the preceding settings.xml format as a guide to declare the repositories you want Maven to pull the build and plugin dependencies from instead.

  3. In the install phase of your build project, instruct AWS CodeBuild to copy your settings.xml file to the build environment's /root/.m2 directory. For example, consider the following snippet from a buildspec.yml file that demonstrates this behavior.

    Copy
    version 0.2 phases: install: commands: - cp ./settings.xml /root/.m2/settings.xml

Build Commands Run as root by Default

Issue: AWS CodeBuild runs your build commands as the root user. This happens even if your related build image's Dockerfile sets the USER instruction to a different user.

Cause: AWS CodeBuild runs all build commands as the root user by default.

Recommended solution: None.

The Bourne Shell (sh) Must Exist in Build Images

Issue: You are using a build image that is not provided by AWS CodeBuild, and your builds fail with the message "build container found dead before completing the build."

Possible cause:The Bourne shell (sh) is not included in your build image. AWS CodeBuild needs sh to run build commands and scripts.

Recommended solution: If sh in not present in your build image, be sure to include it before you start any more builds that use your image. (AWS CodeBuild already includes sh in its build images.)

Error: "AWS CodeBuild is experiencing an issue" When Running a Build

Issue: When you try to run a build project, you receive the following error during the build's PROVISIONING phase: "AWS CodeBuild is experiencing an issue."

Possible cause: Your build is using environment variables that are too large for AWS CodeBuild. AWS CodeBuild can raise errors once the length of all environment variables (all names and values added together) reach a combined maximum of around 5,500 characters.

Recommended solution: Use Amazon EC2 Systems Manager Parameter Store to store large environment variables and then retrieve them from your build spec. Amazon EC2 Systems Manager Parameter Store can store an individual environment variable (name and value added together) that is a combined 4,096 characters or less. To store large environment variables, see Systems Manager Parameter Store and Systems Manager Parameter Store Console Walkthrough in the Amazon EC2 Systems Manager User Guide. To retrieve them, see the parameter-store mapping in Build Spec Syntax.

Error: "BUILD_CONTAINER_UNABLE_TO_PULL_IMAGE" When Using a Custom Build Image

Issue: When you try to run a build that uses a custom build image, the build fails with the error BUILD_CONTAINER_UNABLE_TO_PULL_IMAGE.

Possible causes:

  • The build image's overall uncompressed size is larger than the build environment compute type's available disk space. To check your build image's size, use Docker to run the docker images REPOSITORY:TAG command. For a list of available disk space by compute type, see Build Environment Compute Types.

  • AWS CodeBuild does not have permission to pull the build image from your Amazon EC2 Container Registry (Amazon ECR).

Recommended solutions:

  • Use a larger compute type with more available disk space, or reduce the size of your custom build image.

  • Update the permissions in your repository in Amazon ECR so that AWS CodeBuild can pull your custom build image into the build environment. For more information, see the Amazon ECR Sample.

Builds May Fail When File Names Have Non-US English Characters

Issue: When you run a build that uses files with file names containing non-US English characters (for example, Chinese characters), the build fails.

Possible cause: : Build environments provided by AWS CodeBuild have their default locale set to POSIX. POSIX localization settings are less compatible with AWS CodeBuild and file names that contain non-US English characters and can cause related builds to fail.

Recommended solution: Add the following commands to the pre_build section of your build specification. These commands make the build environment use US English UTF-8 for its localization settings, which is more compatible with AWS CodeBuild and file names that contain non-US English characters.

For build environments based on Ubuntu:

Copy
pre_build: commands: - export LC_ALL="en_US.UTF-8" - locale-gen en_US en_US.UTF-8 - dpkg-reconfigure locales

For build environments based on Amazon Linux:

Copy
pre_build: commands: - export LC_ALL="en_US.utf8"

Builds Might Fail When Getting Parameters from Amazon EC2 Parameter Store

Issue: When a build tries to get the value of one or more parameters stored in Amazon EC2 Parameter Store, the build fails in the DOWNLOAD_SOURCE phase with the following error: "Parameter does not exist."

Possible causes: The service role the build project relies on does not have permission to call the ssm:GetParameters action or the build project uses a service role that is generated by AWS CodeBuild and allows calling the ssm:GetParameters action, but the parameters have names that do not start with /CodeBuild/.

Recommended solutions:

  • If the service role was not generated by AWS CodeBuild, update its definition to allow AWS CodeBuild to call the ssm:GetParameters action. For example, the following policy statement allows calling the ssm:GetParameters action to get parameters with names starting with /CodeBuild/:

    Copy
    { "Version": "2012-10-17", "Statement": [ { "Action": "ssm:GetParameters", "Effect": "Allow", "Resource": "arn:aws:ssm:REGION_ID:ACCOUNT_ID:parameter/CodeBuild/*" } ] }
  • If the service role was generated by AWS CodeBuild, update its definition to allow AWS CodeBuild to access parameters in Amazon EC2 Parameter Store with names other than those starting with /CodeBuild/. For example, the following policy statement allows calling the ssm:GetParameters action to get parameters with the specified name:

    Copy
    { "Version": "2012-10-17", "Statement": [ { "Action": "ssm:GetParameters", "Effect": "Allow", "Resource": "arn:aws:ssm:REGION_ID:ACCOUNT_ID:parameter/PARAMETER_NAME" } ] }