排查构建错误

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

构建是否可以在本地完成?

在对 Cloud Build 错误进行问题排查时,在任何情况下都应该首先确认您是否可以在本地构建。如果构建在本地无法运行,则说明此问题的根本原因不是来自 Cloud Build。首先需要在本地诊断并修复问题。

您是否查看了构建日志?

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

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

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

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 上部署时看到以下错误:

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

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

在 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 上部署

在 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 以外的范围。如需查看相关说明,请参阅为专用池设置环境

由于缺少 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 权限,该服务帐号需要此权限才能运行构建触发器。您可以通过将 Cloud Build Service Account IAM 角色授予 [PROJECT_NUMBER]@cloudbuild.gserviceaccount.com 来解决此错误。有关授予此角色的说明,请参阅配置 Cloud Build 服务帐号的访问权限

I/O 超时错误

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

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

此错误通常在构建尝试访问专用网络中的资源时发生。通过 Cloud Build 运行的构建可以访问公共互联网中的私有资源,例如代码库或注册表中的资源。但是,构建无法访问专用网络中的资源。

4xx 客户端错误

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

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

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

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

后续步骤