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](https://docs.cloud.google.com/build/docs/securing-builds/store-manage-build-logs)
to get more information about the build error. Logs written to `stdout` or
`stderr` are
[viewable using the Google Cloud console and the gcloud CLI](https://docs.cloud.google.com/build/docs/securing-builds/store-manage-build-logs#view-cloud-build).

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

You see the following error when trying to run a
[build manually](https://docs.cloud.google.com/build/docs/running-builds/start-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](https://docs.cloud.google.com/build/docs/securing-builds/store-manage-build-logs#store-default-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:

- Use the default logs bucket, and grant the [Project Viewer](https://docs.cloud.google.com/iam/docs/roles-overview#basic)
  role and the [Cloud Build Editor](https://docs.cloud.google.com/build/docs/iam-roles-permissions#predefined_roles)
  role to the user running the build. For instructions on granting this permission,
  see [Configure access to Cloud Build resources](https://docs.cloud.google.com/build/docs/securing-builds/configure-access-to-resources).

- Create your own Cloud Storage bucket to store logs. For instructions see
  [Storing build logs in a user-created bucket](https://docs.cloud.google.com/build/docs/securing-builds/store-manage-build-logs#store-custom-bucket).

## Builds fail due to missing `iam.serviceAccounts.actAs` permission

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

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

To address this error, configure your
[specified Cloud Build service account](https://docs.cloud.google.com/build/docs/securing-builds/configure-user-specified-service-accounts)
or the [default Cloud Build service account](https://docs.cloud.google.com/build/docs/cloud-build-service-account)
to impersonate the service account of the managed service that you're using
for your build. For more information about this task, see
[Configure Cloud Build service account impersonation for managed services](https://docs.cloud.google.com/build/docs/deploying-builds/cb-sa-imp).

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

- [Configure user-specified service accounts](https://docs.cloud.google.com/build/docs/securing-builds/configure-user-specified-service-accounts)
- [Cloud Build default service account](https://docs.cloud.google.com/build/docs/cloud-build-service-account)
- [Understanding IAM roles](https://docs.cloud.google.com/iam/docs/understanding-roles)
- [Granting permissions to the Cloud Build default service account](https://docs.cloud.google.com/build/docs/securing-builds/configure-access-for-cloud-build-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](https://docs.cloud.google.com/build/docs/deploying-builds/deploy-functions).

## 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](https://docs.cloud.google.com/build/docs/securing-builds/configure-user-specified-service-accounts)
or the [default service account](https://docs.cloud.google.com/build/docs/securing-builds/configure-access-for-cloud-build-service-account).

## Build submit failure due to missing service agent permissions

If the Cloud Build [service agent](https://docs.cloud.google.com/build/docs/securing-builds/configure-access-for-cloud-build-service-account#service-agent-permissions) 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](https://console.cloud.google.com/iam-admin/iam)
   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](https://console.cloud.google.com/logs/query)
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](https://docs.cloud.google.com/build/docs/automating-builds/create-manage-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](https://docs.cloud.google.com/vpc-service-controls/docs/supported-products#table_pubsub).
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.

## 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 a `git pull` or `git fetch`
on a remote branch from a private repository:

    fatal: could not read Username for '<REMOTE_URL>': No such device or address

This error is expected on private repositories, as the git credential helper is
intentionally removed after the initial cloning of the repository.
To fetch remote branches from a private repository, manually set up
authorization credentials (API Tokens, SSH Keys) as a build step.
[Learn more about accessing private GitHub repositories](https://docs.cloud.google.com/build/docs/access-private-github-repos).

## 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](https://docs.cloud.google.com/build/docs/access-private-github-repos).

## Builds fail due to `No route to host` error

You see the following or similar error when running a build in a [private pool](https://docs.cloud.google.com/build/docs/private-pools/private-pools-overview):

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

Cloud Build runs its [Cloud builders](https://docs.cloud.google.com/build/docs/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](https://docs.cloud.google.com/build/docs/private-pools/set-up-private-pool-environment#setup-private-connection).

## 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 no
logs are generated.

Check the following in your configuration:

- You've configured a lower `queueTtl` value (e.g. 20s).

  Increase the value in your schema and run the build again. See
  [`queueTtl`](https://docs.cloud.google.com/build/docs/build-config-file-schema#queuettl) for more
  information.
- 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 see [Quotas and Limits](https://docs.cloud.google.com/build/quotas).
- 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 new
  virtual machine to start. See
  [Machine types](https://docs.cloud.google.com/build/docs/api/reference/rest/v1/projects.builds#machinetype)
  for more information.

  You can try [changing the machine type](https://docs.cloud.google.com/build/docs/private-pools/create-manage-private-pools).
- 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, and
  thus determines the limit of concurrent builds, even if it's lower than the
  Concurrent Builds quota. Builds are queued if there are no worker VMs
  available in the pool.

  This occurs when the available IP addresses within the designated subnet are
  fully utilized, leaving no addresses for new Cloud Build workers to
  allocate. 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 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](https://docs.cloud.google.com/build/docs/private-pools/create-manage-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 tries to access resources in a private
network but fails. By default, builds run using 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](https://docs.cloud.google.com/build/docs/private-pools/use-in-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](https://docs.cloud.google.com/build/docs/build-config). 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](https://docs.cloud.google.com/build/docs/automating-builds/create-github-app-triggers).
- 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](https://cloud.google.com/contact) to get your quotas increased for
this particular region.

## Timeout issues when pulling images from Docker registry

You see the following timeout errors in your Cloud Build log after
running a build:

    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](https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_pull.md) 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, for example the following:

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

> [!CAUTION]
> **Caution:** Using a token with a long lifespan, or a token that does not expire, could increase the risk of unauthorized access to your software supply chain. When using a custom token, set the shortest lifespan possible to complete the task.

## 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.

## Failed to create private pool: Worker pool isn't peered to Service Networking API

You tried to create a private pool. However, you receive the following error
message:

    Failed to create private pool private-worker-pool: generic::failed_precondition: network "projects/PROJECT_NAME/global/networks/vpc-scmdev-lab-vpc" is not peered to the Service Networking API; please check your configuration and the documentation for troubleshooting and setting up your pool 

For builds to access private resources from your Virtual Private Cloud network, you must
set up a peering connection between your Virtual Private Cloud network and the
Virtual Private Cloud network where private pools reside. For instructions, see
[Setting up a private connection between your VPC network and the service producer network](https://docs.cloud.google.com/build/docs/private-pools/set-up-private-pool-to-use-in-vpc-network#setup-private-connection).

## Failed to create private pool: cannot access peered_network config

If you're using a Shared VPC or have previously deleted the
Service Networking service agent, private pool creation might fail
with an error similar to the following:

    generic::permission_denied: cannot access peered_network config.

To fix this issue, make sure the Service Networking service agent
(`service-PROJECT_NUMBER@service-networking.iam.gserviceaccount.com`) exists in
your service project and has the necessary permissions.

Create the service account if it's missing:

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

Grant the service account the required `roles/servicenetworking.serviceAgent`
role:

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

## What's next

- Learn how to [manage build logs](https://docs.cloud.google.com/build/docs/securing-builds/store-manage-build-logs).

## Build logs appear out of order

You ran build steps that output logs and you noticed that `stderr` (error) logs appear in the UI before their corresponding `stdout` (standard output) logs. The logs appear chronologically out of order.

This ordering is standard Linux and Docker stream buffering behavior. When code runs in a non-TTY environment, like a build container, `stdout` is block-buffered (delayed until the buffer fills up), while `stderr` remains unbuffered (prints immediately).

To bypass this ordering method and guarantee strict log ordering, you must explicitly disable buffering in your build step's execution environment.

**Python:**
Set the `PYTHONUNBUFFERED` environment variable:
`yaml
steps:
- name: 'python:3'
env: ['PYTHONUNBUFFERED=1']
script: |
python main.py`

**C/C++ and Bash Scripts:**
Use the `stdbuf` command to force line-buffering:
`yaml
steps:
- name: 'ubuntu'
script: |
stdbuf -oL ./your_binary`

**Java:**
Java does not natively support disabling buffering using a flag, but you can force an immediate flush in your code after critical log statements:
`java
System.out.println("Log message");
System.out.flush();`