Troubleshooting Amazon CodeBuild

Use the information in this topic to help you identify, diagnose, and address issues. To learn how to log and monitor CodeBuild builds to troubleshoot issues, see Logging and monitoring.

Apache Maven builds reference artifacts from the wrong repository

Issue: When you use Maven with an Amazon 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: 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.

<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:

Build commands run as root by default

Issue: Amazon 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: By default, CodeBuild runs all build commands as the root user.

Recommended solution: None.

Builds might fail when file names have non-U.S. English characters

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

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

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

For build environments based on Ubuntu:

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:

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 error Parameter does not exist.

Possible cause: 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 Amazon CodeBuild and allows calling the ssm:GetParameters action, but the parameters have names that do not start with /CodeBuild/.

Recommended solutions:

Cannot access branch filter in the CodeBuild console

Issue: The branch filter option is not available in the console when you create or update an Amazon CodeBuild project.

Possible cause: The branch filter option is deprecated. It has been replaced by webhook filter groups, which provide more control over the webhook events that trigger a new build in CodeBuild.

Recommended solution: To migrate a branch filter that you created before the introduction of webhook filters, create a webhook filter group with a HEAD_REF filter with the regular expression ^refs/heads/branchName$. For example, if your branch filter regular expression was ^branchName$, then the updated regular expression you put in the HEAD_REF filter is ^refs/heads/branchName$. For more information, see Bitbucket webhook events and Filter GitHub webhook events (console).

Cannot view build success or failure

Issue: You cannot see the success or failure of a retried build.

Possible cause: The option to report your build's status is not enabled.

Recommended solutions: Enable Report build status when you create or update a CodeBuild project. This option tells CodeBuild to report back the status when you trigger a build. For more information, see reportBuildStatus in the Amazon CodeBuild API Reference.

Build status not reported to source provider

Issue: After allowing build status reporting to a source provider, such as GitHub or Bitbucket, the build status is not updated.

Possible cause: The user associated with the source provider does not have write access to the repo.

Recommended solutions: To be able to report the build status to the source provider, the user associated with the source provider must have write access to the repo. If the user does not have write access, the build status cannot be updated. For more information, see Source provider access.

Cannot find and select the base image of the Windows Server Core 2019 platform

Issue: You cannot find or select the base image of the Windows Server Core 2019 platform.

Possible cause: You are using an Amazon Region that does not support this image.

Recommended solutions: Use one of the following Amazon Regions where the base image of the Windows Server Core 2019 platform is supported:

Earlier commands in buildspec files are not recognized by later commands

Issue: The results of one or more commands in your buildspec file are not recognized by later commands in the same buildspec file. 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 buildspec file version 0.1, Amazon 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 that you use build spec version 0.2, which solves this issue. If you must use buildspec version 0.1, we recommend that you use 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 buildspec file. For more information, see Shells and commands in build environments and Environment variables in build environments.

Error: "Access denied" when attempting to download cache

Issue: When attempting to download the cache on a build project that has cache enabled, you receive an Access denied error.

Possible causes:

Recommended solution: For first time use, it's normal to see this immediately after updating the cache configuration. If this error persists, then you should check to see if your service role has s3:GetObject and s3:PutObject permissions to the S3 bucket that is holding the cache. For more information, see Specifying S3 permissions in the Amazon S3 Developer Guide.

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.

Error: "Build container found dead before completing the build. build container died because it was out of memory, or the Docker image is not supported. ErrorCode: 500"

Issue: When you try to use a Microsoft Windows or Linux container in Amazon CodeBuild, this error occurs during the PROVISIONING phase.

Possible causes:

Recommended solutions:

Error: "Cannot connect to the Docker daemon" when running a build

Issue: Your build fails and you receive an error similar to Cannot connect to the Docker daemon at unix:/var/run/docker.sock. Is the docker daemon running? in the build log.

Possible cause: You are not running your build in privileged mode.

Recommended solution: To fix this error, you must enable privileged mode and update your buildspec using the following instructions.

To run your build in privileged mode, follow these steps:

You'll also need to start the Docker daemon inside your container. The install phase of your buildspec might look similar to this.

phases:
  install:
    commands:
      - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 &
      - timeout 15 sh -c "until docker info; do echo .; sleep 1; done"

For more information about the OverlayFS storage driver referenced in the buildspec file, see Use the OverlayFS storage driver on the Docker website.

- timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done"

To learn more about how to build and run a Docker image by using Amazon CodeBuild, see Docker in custom image sample for CodeBuild.

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 error Code:InvalidInputException, Message:CodeBuild is not authorized to perform: sts:AssumeRole on arn:aws:iam::account-ID:role/service-role-name.

Possible causes:

Recommended solutions:

Error: "Error calling GetBucketAcl: Either the bucket owner has changed or the service role no longer has permission to called s3:GetBucketAcl"

Issue: When you run a build, you receive an error about a change in ownership of an S3 bucket and GetBucketAcl permissions.

Possible cause: You added the s3:GetBucketAcl and s3:GetBucketLocation permissions to your IAM role. These permissions secure your project's S3 bucket and ensure that only you can access it. After you added these permissions, the owner of the S3 bucket changed.

Recommended solution: Verify you are an owner of the S3 bucket, and then add permissions to your IAM role again. For more information, see Secure access to S3 buckets.

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 S3 output bucket (the bucket where Amazon CodeBuild stores its output from the build) is in an Amazon Region different from the CodeBuild build project.

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

Error: "Git clone failed: Unable to access 'your-repository-URL': SSL certificate problem: Self signed certificate"

Issue: When you try to run a build project, the build fails with this error.

Possible cause: Your source repository has a self-signed certificate, but you have not chosen to install the certificate from your S3 bucket as part of your build project.

Recommended solutions:

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 S3 bucket, and that bucket is in an Amazon Region different from the Amazon CodeBuild build project.

Recommended solution: Update the build project's settings to point to a bucket that contains your pre-built source code. Make sure that bucket is in the same Amazon Region as the build project.

Error: "This build image requires selecting at least one runtime version."

Issue: When you run a build, the DOWNLOAD_SOURCE build phase fails with the error YAML_FILE_ERROR: This build image requires selecting at least one runtime version.

Possible cause: Your build uses version 1.0 or later of the Amazon Linux 2 (AL2) standard image, or version 2.0 or later of the Ubuntu standard image, and a runtime is not specified in the buildspec file.

Recommended solution: If you use the aws/codebuild/standard:2.0 CodeBuild managed image, you must specify a runtime version in the runtime-versions section of the buildspec file. For example, you might use the following buildspec file for a project that uses PHP:

version: 0.2

phases:
  install:
    runtime-versions:
        php: 7.3
  build:
    commands:
      - php --version
artifacts:
  files:
    -  README.md

For more information, see Specify runtime versions in the buildspec file.

Error: "QUEUED: INSUFFICIENT_SUBNET" when a build in a build queue fails

Issue: A build in a build queue fails with an error similar to QUEUED: INSUFFICIENT_SUBNET.

Possible causes: The IPv4 CIDR block specified for your VPC uses a reserved IP address. The first four IP addresses and the last IP address in each subnet CIDR block are not available for you to use and cannot be assigned to an instance. For example, in a subnet with CIDR block 10.0.0.0/24, the following five IP addresses are reserved:

Recommended solutions: Check if your VPC uses a reserved IP address. Replace any reserved IP address with one that is not reserved. For more information, see VPC and subnet sizing in the Amazon VPC User Guide.

Error: "Unable to download cache: RequestError: Send request failed caused by: x509: Failed to load system roots and no roots provided"

Issue: When you try to run a build project, the build fails with this error.

Possible cause: You configured caching as part of your build project and are using an older Docker image that includes an expired root certificate.

Recommended solution: Update the Docker image that is being used in your Amazon CodeBuild the project. For more information, see Docker images provided by CodeBuild.

Error: "Unable to download certificate from S3. AccessDenied"

Issue: When you try to run a build project, the build fails with this error.

Possible causes:

Recommended solutions:

Error: "Unable to locate credentials"

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

Possible causes:

Recommended solutions:

RequestError timeout error when running CodeBuild in a proxy server

Issue: You receive a RequestError error similar to one of the following:

Possible causes:

Recommended solutions:

The bourne shell (sh) must exist in build images

Issue: You are using a build image that is not provided by Amazon 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. 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. (CodeBuild already includes sh in its build images.)

Warning: "Skipping install of runtimes. runtime version selection is not supported by this build image" when running a build

Issue: When you run a build, the build log contains this warning.

Possible cause: Your build does not use version 1.0 or later of the Amazon Linux 2 (AL2) standard image, or version 2.0 or later of the Ubuntu standard image, and a runtime is specified in a runtime-versions section in your buildspec file.

Recommended solution: Be sure your buildspec file does not contain a runtime-versions section. The runtime-versions section is only required if you use the Amazon Linux 2 (AL2) standard image or later or the Ubuntu standard image version 2.0 or later.

Error: "Unable to verify JobWorker identity" when opening the CodeBuild console

Issue: When you open the CodeBuild console, an "Unable to verify JobWorker identity" error message is displayed.

Possible cause: The IAM role that is used for console access has a tag with jobId as the key. This tag key is reserved for CodeBuild and will cause this error if it is present.

Recommended solution: Change any custom IAM role tags that have the key jobId to have a different key, such as jobIdentifier.

Build failed to start

Issue: When starting a build, you receive a Build failed to start error message.

Possible cause: The number of concurrent builds has been reached.

Recommended solutions: Wait until other builds are complete, or increase the concurrrent build limit for the project, and start the build again. For more information, see Project configuration.

Accessing GitHub metadata in locally cached builds

Issue: In some cases, the .git directory in a cached build is a text file and not a directory.

Possible causes: When local source caching is enabled for a build, CodeBuild creates a gitlink for the .git directory. This means that the .git directory is actually a text file containing the path to the directory.

Recommended solutions: In all cases, use the following command to obtain the Git metadata directory. This command will work no matter the format of .git:

git rev-parse --git-dir

AccessDenied: The bucket owner for the report group does not match the owner of the S3 bucket...

Issue: When uploading test data to an Amazon S3 bucket, CodeBuild is unable to write the test data to the bucket.

Possible causes:

Recommended solutions:

Error: "Your credentials lack one or more required privilege scopes" when creating a CodeBuild project with CodeConnections

Issue: When creating a CodeBuild project with CodeConnections, you don't have permission to install a Bitbucket webhook.

Possible causes:

Recommended solutions: