排查构建错误

本页面介绍问题排查策略，以及运行构建时可能看到的一些常见错误消息的解决方案。

您是否查看了构建日志？

使用 Logging 或 Cloud Storage 构建日志可以获取有关构建错误的详细信息。写入 stdout 或 stderr 的日志会自动显示在 Google Cloud 控制台中。

由于用户无权访问构建日志，手动构建失败

您尝试运行手动构建时看到以下错误：

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

您之所以看到此错误，是因为 Cloud Build 要求运行手动构建并使用默认 Cloud Storage 日志存储桶的用户除了具有 Cloud Build Editor 角色之外，还具有 Project Viewer IAM 角色。若要解决此错误，您可以执行以下任一操作：

由于缺少服务账号权限，构建失败

Cloud Build 使用特殊服务账号代表您执行构建。如果 Cloud Build 服务账号没有执行任务所需的权限，您将看到以下错误：

Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [CLOUD_BUILD_SERVICE_ACCOUNT]@PROJECT.iam.gserviceaccount.com

要解决此错误，请向此服务账号授予必需的权限。使用以下页面中的信息来确定向 Cloud Build 服务账号授予的权限：

由于缺少服务账号导致构建失败通常在尝试使用 Cloud Build 部署时发生。

在 Cloud Functions 上部署时出现“权限遭拒”错误

您尝试使用 Cloud Functions 函数时，看到以下错误：

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

若要解决此错误，请向 Cloud Build 服务账号授予 Cloud Functions Developer 角色。

在 Cloud Functions 上部署时缺少权限错误

您尝试在 Cloud Functions 上部署时看到以下错误：

Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [CLOUD_BUILD_SERVICE_ACCOUNT]@PROJECT.iam.gserviceaccount.com

如需解决此错误，请将 Service Account User 角色授予 Cloud Build 服务帐号。

在 App Engine 上部署时出错

您尝试在 App Engine 上部署时看到以下错误：

Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [CLOUD_BUILD_SERVICE_ACCOUNT]@PROJECT.iam.gserviceaccount.com

若要解决此错误，请向 Cloud Build 服务账号授予 App Engine Admin 角色。

在 GKE 上部署时出错

您尝试在 GKE 上部署时看到以下错误：

Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [CLOUD_BUILD_SERVICE_ACCOUNT]@PROJECT.iam.gserviceaccount.com

若要解决此错误，请向 Cloud Build 服务账号授予 GKE Developer 角色。

在 Cloud Run 上部署时出错

您尝试在 Cloud Run 上部署时看到以下错误：

Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [CLOUD_BUILD_SERVICE_ACCOUNT]@PROJECT.iam.gserviceaccount.com

您之所以看到此错误，是因为 Cloud Build 服务账号缺少在 Cloud Run 上部署所需的 IAM 权限。如需了解如何授予必要的权限，请参阅在 Cloud Run 上部署。

由于缺少 cloudbuild.builds.create 权限，构建触发器失败

运行构建触发器时您看到以下错误：

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

构建触发器使用 Cloud Build 服务账号创建构建。上述错误表示 Cloud Build 服务帐号缺少 cloudbuild.builds.create IAM 权限，服务帐号运行构建触发器需要该权限。您可以通过向 [PROJECT_NUMBER]@cloudbuild.gserviceaccount.com 授予 Cloud Build Service Account IAM 角色来解决此错误。如需了解如何授予此角色，请参阅为 Cloud Build 服务账号配置访问权限。

触发器失败并显示 Couldn't read commit 个错误

运行构建触发器时您看到以下错误：

  Failed to trigger build: Couldn't read commit

如果您尝试使用不存在的分支触发构建，Cloud Build 会返回此消息。检查目录名称的拼写和一致性。如需了解有关触发器设置的说明，请参阅创建和管理构建触发器。

无法创建 Pub/Sub 触发器

您在创建 Pub/Sub 触发器时看到以下错误：

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

此错误表示您的项目中的 Pub/Sub API 受到限制。限制 Pub/Sub API 的项目会限制创建推送订阅的能力。您可以暂时从边界内的受限服务中移除 Pub/Sub，创建触发器并再次限制 Pub/Sub API 以解决错误。

在 Container Registry 中存储映像时出错

构建尝试将构建的映像存储到 Container Registry 时您看到以下错误：

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

您之所以看到此错误，是因为 Cloud Build 服务账号没有在 Container Registry 中存储容器映像所需的 Storage Admin 角色。

由于 SSH 授权无效，构建失败

运行构建时您看到以下错误：

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

此错误表示 SSH 授权存在问题。一个常见的示例是，通过 Cloud Build 访问私有 GitHub 代码库时发生的 SSH 授权错误。如需了解如何为 GitHub 设置 SSH，请参阅访问私有 GitHub 代码库。

由于 No route to host 错误，构建失败

在专用池中运行构建时，您会看到以下或类似错误：

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

Cloud Build 使用 Docker 容器在 Google 管理的项目内的虚拟机上运行其 Cloud Build 构建器。Docker 桥接接口（以及因此连接到此接口的容器）分配的 IP 范围为 192.168.10.0/24，这使得无法与同一子网中的外部主机进行通信。在配置专用池期间，为项目中的资源分配 IP 范围时，我们建议选择 192.168.10.0/24 以外的范围。如需查看相关说明，请参阅为专用池设置环境。

由于未启用任何外部 IP，无法连接到外部资源

从专用池连接到外部资源时，您会看到以下错误：

 Failed to connect to <external_domain>: Connection timed out

专用池使用外部 IP 访问公共互联网上的资源，例如外部代码库。创建或更新专用池时，请选中相应复选框，将外部 IP 分配给专用池。如需了解如何在专用池中创建或更新字段，请参阅创建和管理专用池。

I/O 超时错误

运行构建时您看到以下错误：

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

当您的构建尝试访问专用网络中的资源但失败时，可能会发生此错误。默认情况下，通过 Cloud Build 运行的构建可以访问公共互联网中的专用资源，例如代码库或注册表中的资源。但是，只有在您使用专用池并将其配置为访问专用网络时，构建才能访问专用网络中的资源。请参阅在专用网络中使用 Cloud Build。

4xx 客户端错误

这组错误表示可能由于发送构建请求的用户一侧的错误而导致构建请求不成功。4xx 客户端错误的一些示例包括：

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

如果出现 4xx 客户端错误，请查看构建日志，看看其是否包含有关此错误原因的详细信息。导致客户端错误的一些常见原因包括：

  • 您指定的来源位置没有任何新内容要提交，并且工作树干净。在这种情况下，请检查您的源代码位置，然后尝试再次构建。
  • 您的代码库不包含构建配置文件。如果是这种情况，请将构建配置文件上传到您的代码库，然后再次运行构建。
  • 您指定的触发器 ID 不正确。
  • 您最近在安装 GitHub 应用后添加了新代码库，Cloud Build 无权访问新代码库。如果是这种情况，请将您的新代码库连接到 Cloud Build。
  • 您需要向服务帐号授予其他权限。

由于配额限制，构建失败

您会看到以下错误，指示构建因特定区域的配额限制而失败：

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

请与 Cloud Customer Care 团队联系，以增加您在此特定区域的配额。如需详细了解配额和限制，请参阅配额和限制。

从 Docker 注册表拉取映像时出现超时问题

运行后，您会在 Cloud 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

如需解决该错误，请使用 crane 下载 Docker 映像，然后继续将该映像加载到 Cloud Build Docker 映像上。

将以下代码段添加到您的 cloudbuild.yaml 文件中。

...
  # 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：您的 HTTP 代理的地址（例如 https://proxy.example.com:8888/）。

图片加载完毕后，现有的 cloudbuid.yaml 步骤应该可以正常使用，例如

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

长时间运行的 Docker 步骤存在 Unauthenticated 个错误

如果构建步骤涉及运行超过一小时的 Docker 命令（例如将大型映像推送到 Artifact Registry），则可能会因身份验证错误而失败。Cloud Build 每小时刷新一次身份验证令牌，但 Docker 可能无法提取这些新令牌，从而导致身份验证问题。您可以将具有自定义有效期的令牌写入到文件中，供 Docker 命令引用该令牌。

后续步骤