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

Did you look at the build logs?

UseLogging or Cloud Storage build logsto get more information about the build error. Logs written tostdout orstderr areviewable using the Google Cloud console and the gcloud CLI.

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

You see the following error when trying to run abuild manually:

AccessDeniedAccessdenied.[EMAIL_ADDRESS]doesnothavestorage.objects.getaccesstotheGoogleCloudStorageobject.

You see this error because Cloud Build requires that users runningmanual builds and using thedefault Cloud Storage logs buckethave the Project Viewer IAM role in addition to the Cloud BuildEditor role. To address this error, you can do one of the following:

• Use the default logs bucket, and grant theProject Viewerrole and theCloud Build Editorrole to the user running the build. For instructions on granting this permission,seeConfigure access to Cloud Build resources.

• Create your own Cloud Storage bucket to store logs. For instructions seeStoring build logs in a user-created bucket.

Builds fail due to missingiam.serviceAccounts.actAs permission

You see the following error when trying to deploy a build using a managedservice such as Cloud Run or App Engine:

Missingnecessarypermissioniam.serviceAccounts.actAsfor[USER]ontheserviceaccount[SERVICEACCOUNT]

To address this error, configure yourspecified Cloud Build service accountor thedefault Cloud Build service accountto impersonate the service account of the managed service that you're usingfor your build. For more information about this task, seeConfigure Cloud Build service account impersonation for managed services.

For additional information about service accounts and permissions, see thefollowing topics:

• Configure user-specified service accounts
• Cloud Build default service account
• Understanding IAM roles
• Granting permissions to the Cloud Build default service account

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.

Build trigger fails due to missingcloudbuild.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 indicatesthat the service account is missing thecloudbuild.builds.createIAM permission, which is required for the service account to runa build trigger. You can resolve this error by granting theCloud Build Service AccountIAM role to either youruser-specified service accountor thedefault service account.

Build submit failure due to missing service agent permissions

If the Cloud Buildservice agent isdeleted or lacking permissions then it may cause the following error whensubmitting 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. Toresolve this permission issue, follow these steps:

1. Ensure the Cloud Build service agent exists. You can view theservice agent for a project by going to theIAM page in the Google Cloud consoleand selecting theShow google managed service accounts checkbox. Ifit's not there, then you can create it by running the followinggcloud CLI command:

   gcloudbetaservicesidentitycreate--service=cloudbuild.googleapis.com\--project=PROJECT_ID

2. Next, grant theroles/cloudbuild.serviceAgent IAM role to theCloud Build service agent:

   gcloudprojectsadd-iam-policy-bindingPROJECT_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 fordriving 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 ofthem are removing permissions from the service agent(service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com).If so, look at theprotoPayload.authenticationInfo.principalEmail in that log to determine the IAM identity responsible for removing either the permission or theroles/cloudbuild.serviceAgent role containing the permission listed in theerror message.

Trigger fails withCouldn'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, seeCreate 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 yourproject. Projects restricting the Pub/Sub APIlimit the ability to create Push Subscriptions.You can temporarily remove Pub/Sub from restricted services inyour perimeter, create the trigger and restrict the Pub/Sub APIagain to resolve the error.

Unable to Pull or Fetch branches from a private repository due to error:fatal: could not read Username

You see the following error when trying to perform agit pull orgit fetchon a remote branch from a private repository:

fatal:couldnotreadUsernamefor'<REMOTE_URL>':Nosuchdeviceoraddress

This error is expected on private repositories, as the git credential helper isintentionally removed after the initial cloning of the repository.To fetch remote branches from a private repository, manually set upauthorization credentials (API Tokens, SSH Keys) as a build step.Learn more about accessing private GitHub repositories.

Builds fail due to invalid ssh authorization

You see the following error when running a build:

Couldnotparsessh:[default]:invalidemptyssh-agentsocket,makesureSSH_AUTH_SOCKisset

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

Builds fail due toNo route to host error

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

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

Cloud Build runs itsCloud builders on the virtual machine in the Google-managed projectusing the Docker containers. The Docker bridge interface (and consequently thecontainers connected to this interface) is assigned an IP range of192.168.10.0/24, which makes the communication with the externalhosts 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, seeSetting up your environment for private pools.

Builds fails with error message: "Expired," and doesn't show any logs

You trigger or submit a build and it fails, throwing an "Expired" error, and nologs are generated.

Check the following in your configuration:

• You've configured a lowerqueueTtl value (e.g. 20s).

  Increase the value in your schema and run the build again. SeequeueTtl for moreinformation.

• You've reached the quota for concurrent builds.

  You can request an increase through the Quota page in the Google Cloud console.For more details seeQuotas and Limits.

• You're using a private pool and have chosen the non-default machine.

  The build can take longer to start because it might need to wait for a newvirtual machine to start. SeeMachine typesfor more information.

  You can trychanging the machine type.

• You're using a private pool and have specified an IP range for the pool.

  The physical range of IPs determines the number of worker VMs in the pool, andthus determines the limit of concurrent builds, even if it's lower than theConcurrent Builds quota. Builds are queued if there are no worker VMsavailable in the pool.

  This occurs when the available IP addresses within the designated subnet arefully utilized, leaving no addresses for new Cloud Build workers toallocate. Try increasing the range in the subnet and re-run the build.

Connection to external resource fails due to no external IP enabled

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

 Failed to connect to <external_domain>: Connection timed out

Private pools use external IPs to access resources on the publicinternet, such as external repositories. When creating or updatinga private pool, select the box to assign external IPs to your privatepool. For instructions on Creating or updating fields withinyour private pool, seeCreating 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 privatenetwork but fails. By default, builds run via Cloud Build can accessprivate resources in the public internet such as resources in a repository or aregistry. However, builds can only access resources in a private network if youuse private pools and configure them to access the private network. SeeUsing Cloud Build in a private network.

4xx client errors

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

• **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 containsmore information about the reason for the error. Some common causes for clienterrors include:

• The source location you specified does not have anything new to commit and theworking tree is clean. In this case, check your source code location and trybuilding again.
• Your repository does not contain abuild config file.If this is the case, upload a build config file to your repository and run thebuild again.
• You've specified an incorrect trigger ID.
• You have recently added a new repository after installing the GitHub app, andCloud Build does not have permissions to access the new repository. Ifthis is the caseconnect 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 dueto quota restrictions in a particular region:

Failedtotriggerbuild:generic::failed_precondition:duetoquotarestrictions,cannotrunbuildsinthisregion.Pleasecontactsupport.

Reach out toCloud Customer Care to get your quotas increased forthis particular region.

Timeout issues when pulling images from Docker registry

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

Step#0:Pullingimage:python:3.8.16-alpine3.17Step#0:Errorresponsefromdaemon:Get"https://registry-1.docker.io/v2/":net/http:requestcanceledwhilewaitingforconnection(Client.Timeoutexceededwhileawaitingheaders)Step1/7:FROMpython:3.8.16-alpine3.17Get"https://registry-1.docker.io/v2/":dialtcp34.205.13.154:443:i/otimeout

To resolve the error, download the Docker image usingcrane 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/dockerargs:-a+w-/workspaceentrypoint:chmod# Use crane to download the image through the proxy-name:gcr.io/go-containerregistry/craneenv:-'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/dockerargs:[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 aspushing a large image to Artifact Registry) may fail with an authentication error.Cloud Build refreshes authentication tokens every hour but Docker mayfail to pick these new tokens up resulting in authentication issues. You canwrite your own token with a custom lifespan to file and reference that forDocker commands.

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

• Learn how tomanage build logs.