本頁面由 Cloud Translation API 翻譯而成。

建構錯誤疑難排解

本頁面提供一些常見錯誤訊息的疑難排解策略及解決方案，這些錯誤訊息可能會在執行建構作業時顯示。

您有查看版本記錄嗎？

請使用記錄或 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 編輯者角色外，還必須具備 Project Viewer IAM 角色。如要解決這個錯誤，請執行下列任一操作：

使用預設的記錄值區，並將「專案檢視者」角色和「Cloud Build 編輯者」角色授予執行建構作業的使用者。如需授予這項權限的操作說明，請參閱「設定 Cloud Build 資源的存取權」。
建立 Cloud Storage 值區來儲存記錄。如需操作說明，請參閱「在使用者建立的值區中儲存建構記錄」。

因缺少服務帳戶權限而導致建構作業失敗

如果您用於建構作業的服務帳戶沒有執行工作所需的權限，您會看到類似以下的錯誤訊息：

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

如要解決這個錯誤，請將必要權限授予服務帳戶。請參閱下列頁面中的資訊，判斷要授予建構服務帳戶哪些權限：

嘗試使用 Cloud Build 部署時，常會因缺少建構服務帳戶權限而導致建構失敗。

在 Cloud Run 函式上部署時發生權限遭拒錯誤

嘗試使用 Cloud Run 函式時，會看到下列錯誤：

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

如要解決這項錯誤，請將 Cloud Run 函式開發人員角色授予建構服務帳戶。

在 Cloud Run 函式上部署時發生缺少權限錯誤

嘗試在 Cloud Run 函式上部署時，您會看到類似以下的錯誤訊息：

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

如要解決這項錯誤，請將「服務帳戶使用者」角色授予使用者指定的服務帳戶或預設服務帳戶。

在 App Engine 上部署時發生錯誤

嘗試在 App Engine 上部署時，您會看到類似以下的錯誤訊息：

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

如要解決這項錯誤，請將 App Engine 管理員角色授予使用者指定的服務帳戶或預設服務帳戶。

在 GKE 上部署時發生錯誤

嘗試在 GKE 上部署時，您會看到類似以下的錯誤訊息：

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

如要解決這項錯誤，請為建構服務帳戶授予 GKE 開發人員角色。

在 Cloud Run 上部署時發生錯誤

嘗試在 Cloud Run 上部署時，您會看到類似以下的錯誤訊息：

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

您會看到這項錯誤，是因為您的建構服務帳戶沒有在 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)

建構觸發條件會使用服務帳戶建立建構作業。這個錯誤表示服務帳戶缺少 cloudbuild.builds.create IAM 權限，而服務帳戶必須具備這項權限才能執行建構觸發事件。您可以將 Cloud Build Service Account IAM 角色授予使用者指定的服務帳戶或預設服務帳戶，藉此解決這項錯誤。

缺少服務代理權限，因此無法提交版本

如果 Cloud 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.

在這種情況下，呼叫端是 Cloud Build 服務代理。如要解決這個權限問題，請按照下列步驟操作：

確認 Cloud Build 服務代理是否存在。如要查看專案的服務代理人，請前往 Google Cloud 控制台的 IAM 頁面，然後選取「顯示 Google 代管的服務帳戶」核取方塊。如果沒有，您可以執行下列 gcloud CLI 指令來建立：
```
gcloud beta services identity create --service=cloudbuild.googleapis.com \
    --project=PROJECT_ID
```

接下來，將 roles/cloudbuild.serviceAgent IAM 角色授予 Cloud Build 服務代理：

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

如要驗證哪些 IAM 身分可能導致服務代理權限問題，請按照下列步驟操作：

在 Google Cloud 控制台中開啟 Logs Explorer：

前往「Logs Explorer」

在查詢欄位中輸入下列文字：

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

如果您在使用這項查詢後看到任何記錄項目，請檢查是否有任何項目會從服務代理 (service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com) 移除權限。如果有，請查看該記錄中的 protoPayload.authenticationInfo.principalEmail，以判斷負責移除權限的 IAM 身分，或負責包含錯誤訊息中列出的權限的 roles/cloudbuild.serviceAgent 角色。

觸發條件失敗，發生 `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，以解決錯誤。

因 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 建構工具。Docker 橋接介面 (以及連結至此介面的容器) 會指派 192.168.10.0/24 IP 範圍，因此無法與同一個子網路中的外部主機通訊。在私人資源池設定期間，為專案中的資源分配 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 Proxy 的地址 (例如 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 指令中參照該權杖。

在與虛擬私有雲網路配對的私人集區中，排入佇列的建構作業

當您在私人資源池中執行建構作業時，如果該資源池的服務供應商網路已與您自己的 VPC 網路對等互連，則這兩個網路之間的私人連線必須保持完整。如果刪除私人集區所依賴的私人連線，可能會導致私人集區中斷。這可能會顯示為排隊中的版本，直到最終逾時為止。因此，如果您要刪除私人連線，請務必一併刪除所有使用此私人連線，將服務供應商網路連結至您自己的 VPC 網路的私人集區。

嘗試核准或拒絕超過 2 個月的待處理版本

您無法核准或拒絕超過 2 個月的待處理建構作業。嘗試這麼做可能會導致類似下列的錯誤訊息：

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

如果發生這種情況，請嘗試提交新的版本。

後續步驟

瞭解如何管理建構記錄。