Troubleshooting build errors

This page provides troubleshooting strategies as well as solutions for some common error messages that you might see when running a build.

Did you look at the build logs?

Use Logging or Cloud Storage build logs to get more information about the build error. Logs written to stdout or stderr appear automatically in the Google Cloud console.

Manual builds fail due to user not having access to build logs

You see the following error when trying to run a build manually:

AccessDeniedAccess denied. [EMAIL_ADDRESS] does not have storage.objects.get access to the Google Cloud Storage object.

You see this error because Cloud Build requires that users running manual builds and using the default Cloud Storage logs bucket have the Project Viewer IAM role in addition to the Cloud Build Editor role. To address this error, you can do one of the following:

Builds fail due to missing service account permissions

If the service account you're using for your build doesn't have the necessary permission to perform a task, you'll see something like the following error:

Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [SERVICE ACCOUNT]

To address this error, grant the required permission to the service account. Use the information in the following pages to determine the permission to grant to your build service account:

Build failures due to missing permissions for build service accounts commonly occur when trying to deploy using Cloud Build.

Permission denied error when deploying on Cloud Run functions

You see the following error when trying to use Cloud Run functions:

ResponseError: status=[403], code=[Ok], message=[Permission 'cloudfunctions.functions.get' denied]

To address this error, grant the Cloud Run functions Developer role to your build service account.

Missing permission error when deploying on Cloud Run functions

You see something like the following error when trying to deploy on Cloud Run functions:

Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [SERVICE ACCOUNT]

To address this error, grant the Service Account User role to either your user-specified service account or the default service account.

Error when deploying on App Engine

You see something like the following error when trying to deploy on App Engine:

Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [SERVICE_ACCOUNT]

To address this error, grant the App Engine Admin role to either your user-specified service account or the default service account.

Error when deploying on GKE

You see something like the following error when trying to deploy on GKE:

Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [SERVICE_ACCOUNT]

To address this error, grant the GKE Developer role to your build service account.

Error when deploying on Cloud Run

You see something like the following error when trying to deploy on Cloud Run:

Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [SERVICE_ACCOUNT]

You see this error because your build service account does not have the IAM permissions required to deploy on Cloud Run. For information on granting the necessary permissions, see Deploying on Cloud Run.

Build trigger fails due to missing cloudbuild.builds.create permission

You see something like the following error when running a build trigger:

Failed to trigger build: Permission 'cloudbuild.builds.create' denied on resource 'projects/xxxxxxxx' (or it may not exist)

Build triggers use a service account to create a build. This error indicates that the service account is missing the cloudbuild.builds.create IAM permission, which is required for the service account to run a build trigger. You can resolve this error by granting the Cloud Build Service Account IAM role to either your user-specified service account or the default service account.

Build submit failure due to missing service agent permissions

If the Cloud Build service agent is deleted or lacking permissions then it may cause the following error when submitting a build.

Caller does not have required permission to use project $PROJECT_ID. Grant the caller the roles/serviceusage.serviceUsageConsumer role, or a custom role with the serviceusage.services.use permission, by visiting https://console.developers.google.com/iam-admin/iam/project?project=$PROJECT_ID and then retry. Propagation of the new permission may take a few minutes.

The caller in this scenario is the Cloud Build service agent. To resolve this permission issue, follow these steps:

  1. Ensure the Cloud Build service agent exists. You can view the service agent for a project by going to the IAM page in the Google Cloud console and selecting the Show google managed service accounts checkbox. If it's not there, then you can create it by running the following gcloud CLI command:

    gcloud beta services identity create --service=cloudbuild.googleapis.com \
    --project=PROJECT_ID

  2. Next, grant the roles/cloudbuild.serviceAgent IAM role to the Cloud Build service agent:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com" \
    --role="roles/cloudbuild.serviceAgent"

If you'd like to verify what IAM identity was potentially responsible for driving the service agent permission issue, then follow these steps:

  1. Open Logs Explorer in the Google Cloud console:

    Go to Logs Explorer

  2. Enter the following text in the query field:

    resource.type="project"
log_name="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity"
"service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com"

  3. If you see any log entries after you use this query, check to see if any of them are removing permissions from the service agent (service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com). If so, look at the protoPayload.authenticationInfo.principalEmail in that log to determine the IAM identity responsible for removing either the permission or the roles/cloudbuild.serviceAgent role containing the permission listed in the error message.

Trigger fails with Couldn't read commit error

You see the following error when running a build trigger:

  Failed to trigger build: Couldn't read commit

Cloud Build returns this message if you are trying to trigger a build using a branch that does not exist. Review your directory names for spelling and consistency. For instructions on trigger setup, see Create and manage build triggers.

Unable to create Pub/Sub trigger

You see the following error when creating a Pub/Sub trigger:

  Failed to create trigger: Request is prohibited by organization's policy

This error indicates that the Pub/Sub API is restricted in your project. Projects restricting the Pub/Sub API limit the ability to create Push Subscriptions. You can temporarily remove Pub/Sub from restricted services in your perimeter, create the trigger and restrict the Pub/Sub API again to resolve the error.

Error when storing images in Container Registry

You see something like the following error when your build is trying to store built images to Container Registry:

[EMAIL_ADDRESS] does not have storage.buckets.create access to project [PROJECT_NAME]

You see this error because your build service account does not have the Storage Admin role that is needed to store container images in Container Registry.

Builds fail due to invalid ssh authorization

You see the following error when running a build:

Could not parse ssh: [default]: invalid empty ssh-agent socket, make sure SSH_AUTH_SOCK is set

This error indicates a problem with SSH authorization. A common example is SSH authorization error that happens when accessing private GitHub repositories with Cloud Build. For instructions on setting up SSH for GitHub, see Accessing private GitHub repositories.

Builds fail due to No route to host error

You see the following or similar error when running a build in a private pool:

Unable to connect to the server: dial tcp 192.168.10.XX:<port>: connect: no route to host

Cloud Build runs its Cloud builders on the virtual machine in the Google-managed project using the Docker containers. The Docker bridge interface (and consequently the containers connected to this interface) is assigned an IP range of 192.168.10.0/24, which makes the communication with the external hosts in the same subnet impossible. When allocating the IP ranges for resources in your project(s) during private pool configuration, we recommend selecting a range outside of 192.168.10.0/24. For instructions, see Setting up your environment for private pools.

Connection to external resource fails due to no external IP enabled

You see the following error when connecting to an external resource from a private pool:

 Failed to connect to <external_domain>: Connection timed out

Private pools use external IPs to access resources on the public internet, such as external repositories. When creating or updating a private pool, select the box to assign external IPs to your private pool. For instructions on Creating or updating fields within your private pool, see Creating and managing private pools.

I/O timeout error

You see the following error when running a build:

Timeout - last error: dial tcp IP_ADDRESS: i/o timeout

This error can occur when your build attempts to access resources in a private network but fails. By default, builds run via Cloud Build can access private resources in the public internet such as resources in a repository or a registry. However, builds can only access resources in a private network if you use private pools and configure them to access the private network. See Using Cloud Build in a private network.

4xx client errors

This group of errors indicates that the build request is not successful presumably by fault of the user sending the request. Some examples of 4xx client errors are:

  • **Error**: 404 : Requested entity was not found
  • **Error**: 404 : Trigger not found
  • **Error**: 400 : Failed Precondition
  • **Error**: 403 : Permission denied

When you see a 4xx client error, look at your build logs to see if it contains more information about the reason for the error. Some common causes for client errors include:

  • The source location you specified does not have anything new to commit and the working tree is clean. In this case, check your source code location and try building again.
  • Your repository does not contain a build config file. If this is the case, upload a build config file to your repository and run the build again.
  • You've specified an incorrect trigger ID.
  • You have recently added a new repository after installing the GitHub app, and Cloud Build does not have permissions to access the new repository. If this is the case connect your new repository to Cloud Build.
  • You need to grant another permission to your build service account.

Build fails due to quota restrictions

You see the following error which indicates that a build is failing due to quota restrictions in a particular region:

Failed to trigger build: generic::failed_precondition: due to quota restrictions, cannot run builds in this region. Please contact support.

Reach out to Cloud Customer Care to get your quotas increased for this particular region. To learn more about quotas and limits, see Quotas and limits.

Timeout issues when pulling images from Docker registry

You see the following timeout errors in your Cloud Build log following a run:

Step #0: Pulling image: python:3.8.16-alpine3.17
Step #0: Error response from daemon: Get "https://registry-1.docker.io/v2/": net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)

Step 1/7 : FROM python:3.8.16-alpine3.17
Get "https://registry-1.docker.io/v2/": dial tcp 34.205.13.154:443: i/o timeout

To resolve the error, download the Docker image using crane and proceed to load the image onto the Cloud Build Docker image.

Add the following snippet to your cloudbuild.yaml file.

...
  # Crane runs as a regular user so we need to allow it to access the directory where it saves the image.
  - name: gcr.io/cloud-builders/docker
    args:
    - a+w
    - /workspace
    entrypoint: chmod
  # Use crane to download the image through the proxy
  - name: gcr.io/go-containerregistry/crane
    env: - 'HTTPS_PROXY=HTTPS_PROXY'
    args:
    - pull
    - 'python:3.8.16-alpine3.17'
    - /workspace/image.tar
  # Use docker load to add the image into the local Cloud Build registry
  - name: gcr.io/cloud-builders/docker
    args: [load, --input, "/workspace/image.tar"]
      - .
  • HTTPS_PROXY: The address of your HTTP proxy (e.g. https://proxy.example.com:8888/).

Once the image is loaded, your existing cloudbuid.yaml steps should work as normal e.g.

...
  - name: python:3.8.16-alpine3.17
    args:
    - echo
    - hello
    entrypoint: bash
  # Or use it internally on a Dockerfile
  - name: gcr.io/cloud-builders/docker
    args:
    - build

Unauthenticated errors for long-running Docker steps

Build steps that involve a Docker command that runs for over an hour (such as pushing a large image to Artifact Registry) may fail with an authentication error. Cloud Build refreshes authentication tokens every hour but Docker may fail to pick these new tokens up resulting in authentication issues. You can write your own token with a custom lifespan to file and reference that for Docker commands.

Queued builds in a private pool peered to a VPC network

When you run builds in a private pool that has its service producer network peered to your own VPC network it's important that the private connection between these two networks remains intact. If you delete the private connection that a private pool relied on, you can break the private pool. This can show up as builds that remain queued until they eventually time out. Therefore, if you want to delete a private connection, make sure you also delete any private pools whose service producer network was connected to your own VPC network using this private connection.

Attempting to approve or reject pending builds older than 2 months

You can't approve or reject pending builds older than 2 months. Trying to do so may result in an error message that looks like this:

 404, "message": "Requested entity was not
found.", "status": "NOT_FOUND" } }

If this occurs, try submitting a new build.

What's next