排解建構錯誤等問題

本頁提供疑難排解策略,以及執行建構作業時可能出現的常見錯誤訊息解決方案。

您是否查看過建構記錄?

使用 Logging 或 Cloud Storage 建構作業記錄,進一步瞭解建構錯誤。寫入 stdout 或 stderr 的記錄可使用 Google Cloud 控制台和 gcloud CLI 查看。

使用者無權存取建構記錄,因此手動建構失敗

嘗試手動執行建構作業時,系統顯示下列錯誤:

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

之所以會看到這項錯誤,是因為 Cloud Build 要求執行手動建構作業並使用預設 Cloud Storage 記錄檔 bucket 的使用者,除了 Cloud Build 編輯者角色外,還必須具備專案檢視者 IAM 角色。如要解決這個錯誤,請採取下列任一做法:

缺少 iam.serviceAccounts.actAs 權限,導致建構作業失敗

嘗試使用 Cloud Run 或 App Engine 等代管服務部署建構作業時,您會看到下列錯誤:

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

如要解決這項錯誤,請設定指定的 Cloud Build 服務帳戶或預設 Cloud Build 服務帳戶,模擬用於建構作業的代管服務帳戶。如要進一步瞭解這項工作,請參閱「為代管服務設定 Cloud Build 服務帳戶模擬功能」。

如要進一步瞭解服務帳戶和權限,請參閱下列主題:

在 Cloud Run functions 部署時發生權限遭拒錯誤

嘗試使用 Cloud Run functions 時,出現下列錯誤:

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

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

缺少 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 服務代理。如要解決這個權限問題,請按照下列步驟操作:

  1. 確認 Cloud Build 服務代理存在。如要查看專案的服務代理,請前往 Google Cloud 控制台的「IAM」頁面,然後勾選「顯示 Google 代管的服務帳戶」核取方塊。如果沒有,請執行下列 gcloud CLI 指令來建立:

    gcloud beta services identity create --service=cloudbuild.googleapis.com \
        --project=PROJECT_ID
    
  2. 接下來,將 roles/cloudbuild.serviceAgent IAM 角色授予 Cloud Build 服務代理:

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

如要確認哪個 IAM 身分可能導致服務代理權限問題,請按照下列步驟操作:

  1. 在 Google Cloud 控制台中開啟 Logs Explorer:

    前往 Logs Explorer

  2. 在查詢欄位中輸入下列文字:

    resource.type="project"
    log_name="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity"
    "service-PROJECT_NUMBER@gcp-sa-cloudbuild."
    
  3. 如果使用這項查詢後看到任何記錄項目,請檢查是否有任何項目會移除服務代理 (service-PROJECT_NUMBER@gcp-sa-cloudbuild.) 的權限。 如果是,請查看該記錄中的 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,建立推送訂閱項目的能力會受限。您可以暫時從 perimeter 的受限制服務中移除 Pub/Sub、建立觸發條件,然後再次限制 Pub/Sub API,即可解決錯誤。

發生錯誤,因此無法從私人存放區提取或擷取分支版本:fatal: could not read Username

嘗試對私人存放區的遠端分支執行 git pull 或 git fetch 時,系統會顯示下列錯誤:

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

在存放區初始複製後,Git 憑證輔助程式會刻意移除,因此私人存放區會發生這項錯誤。如要從私人存放區擷取遠端分支,請手動設定授權憑證 (API 權杖、安全殼層金鑰) 做為建構步驟。進一步瞭解如何存取私人 GitHub 存放區。

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 以外的範圍。如需操作說明,請參閱「設定私人集區的環境」。

建構作業失敗,並顯示「Expired」錯誤訊息,且未顯示任何記錄

您觸發或提交建構作業,但作業失敗,並擲回「Expired」錯誤,且未產生任何記錄。

請檢查設定中的下列項目:

  • 您設定的 queueTtl 值較低 (例如 20 秒)。

    請提高結構定義中的值,然後再次執行建構作業。詳情請參閱 queueTtl。

  • 並行建構作業數量已達配額上限。

    您可以透過 Google Cloud 控制台的「配額」頁面申請提高配額。詳情請參閱「配額與限制」。

  • 您使用的是私人集區,且已選擇非預設機器。

    建構作業可能需要等待新的虛擬機器啟動,因此可能需要較長時間才能開始。詳情請參閱「機器類型」。

    您可以嘗試變更機器類型。

  • 您使用的是私人集區,且已為集區指定 IP 範圍。

    IP 的實體範圍會決定集區中的 worker VM 數量,進而決定並行建構作業的限制,即使該限制低於並行建構作業配額也一樣。如果集區中沒有可用的 worker VM,建構作業就會排入佇列。

    當指定子網路中的可用 IP 位址已全數用完,無法再分配給新的 Cloud Build worker 時,就會發生這種情況。請嘗試增加子網路中的範圍,然後重新執行建構作業。

未啟用外部 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」。

私人集區 worker 從內部 GitHub Enterprise 伺服器複製時逾時

在私人集區中執行建構作業,從內部或地端部署 GitHub Enterprise 伺服器複製原始碼時,建構步驟會失敗,並顯示類似下列的連線逾時錯誤:

fatal: unable to access 'https://github.example.com/org/repo.git/': Failed to connect to github.example.com port 443: Connection timed out

或:

fatal: unable to access 'https://github.example.com/org/repo.git/': Could not resolve host: github.example.com

如要解決私人集區 worker 與內部 GitHub Enterprise 伺服器之間的連線逾時問題,請確認下列網路和轉送必要條件:

  • 透過 Service Networking 對等互連匯出自訂路由: 私人集區會在 Google 代管的服務生產者網路中執行,並透過 Service Networking (servicenetworking-googleapis-com) 與虛擬私有雲 (VPC) 網路對等互連。根據預設,虛擬私有雲網路對等互連只會交換子網路路由。如果 GitHub Enterprise 伺服器託管於地端部署環境,或託管於透過 Cloud VPN 或 Cloud Interconnect 連線的外部網路,Cloud Router 得知的動態路由或虛擬私有雲網路中的靜態自訂路由,不會自動與私人集區共用。

    確認虛擬私有雲網路對接設定會將自訂路由匯出至服務生產者網路:

    gcloud compute networks peerings update servicenetworking-googleapis-com \
        --network=VPC_NETWORK \
        --export-custom-routes
    

    將 VPC_NETWORK 替換為與私人集區對接的虛擬私有雲網路名稱。詳情請參閱「路由交換選項」。

  • 為私人主機名稱設定內部 DNS 解析: 如果沒有 DNS 對接,私人集區 worker VM 就無法解析託管於私人 Cloud DNS 區域或地端部署 DNS 伺服器的私人主機名稱:

  • 驗證防火牆規則和 GitHub Enterprise IP 許可清單:

    • 虛擬私有雲和 perimeter 防火牆:確認虛擬私有雲網路中的防火牆規則,以及任何中繼地端部署防火牆,都允許輸入流量從私人集區的分配 IP 位址範圍,傳送至 TCP 通訊埠 443 (HTTPS) 或通訊埠 22 (SSH) 上的 GitHub Enterprise 伺服器。
    • GitHub Enterprise IP 許可清單:如果 GitHub Enterprise 組織或伺服器強制執行 IP 許可清單,請將私人集區對接子網路的已分配 CIDR 範圍新增至許可清單。如果私人集區透過內部 Proxy 或自行管理的網路位址轉譯 (NAT) 閘道轉送輸出流量,請改為將 Proxy 或 NAT IP 位址加入許可清單。
  • 處理非遞移性虛擬私有雲網路對接:虛擬私有雲網路對接不具遞移性。如果 GitHub Enterprise 伺服器部署在次要虛擬私有雲網路,且該網路與託管私人集區的虛擬私有雲網路對接,則私人集區無法透過中介虛擬私有雲網路連至 GitHub Enterprise。如要啟用端對端連線能力,請使用 Cloud VPN、Cloud Interconnect 或中繼 Proxy 連線網路。詳情請參閱「具有多個對接的轉送網路」。

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

Unauthenticated 個錯誤:Docker 步驟執行時間過長

如果建構步驟涉及執行超過一小時的 Docker 指令 (例如將大型映像檔推送至 Artifact Registry),可能會因驗證錯誤而失敗。Cloud Build 每小時會重新整理驗證權杖,但 Docker 可能無法擷取這些新權杖,導致驗證問題。您可以自行編寫具有自訂生命週期的權杖,並在 Docker 指令中參照該權杖。

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

在私人集區中執行建構作業時,如果服務生產者網路與您自己的虛擬私有雲網路對接,請務必確保這兩個網路之間的私人連線保持完整。如果刪除私人集區依賴的私人連線,可能會破壞私人集區。這可能會導致建構作業一直處於佇列中,直到逾時為止。因此,如要刪除私人連線,請務必一併刪除任何私人集區,其服務生產者網路是使用此私人連線連線至您自己的虛擬私有雲網路。

嘗試核准或拒絕超過 2 個月的待處理建構作業

您無法核准或拒絕超過 2 個月的待處理建構作業。否則可能會看到類似下方的錯誤訊息:

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

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

無法建立私人集區:worker 集區未與 Service Networking API 對接

您嘗試建立私人集區,但您收到下列錯誤訊息:

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 

如要讓建構作業存取虛擬私有雲網路中的私人資源,您必須在虛擬私有雲網路與私人集區所在的虛擬私有雲網路之間,設定對等互連連線。如需操作說明,請參閱「在虛擬私有雲網路與服務生產者網路之間設定私人連線」。

無法建立私人集區:無法存取 peered_network 設定

如果您使用 Shared VPC,或先前刪除了 Service Networking 服務代理,私人集區建立作業可能會失敗,並顯示類似下列的錯誤:

generic::permission_denied: cannot access peered_network config.

如要修正這個問題,請確認服務專案中存在 Service Networking 服務代理 (service-PROJECT_NUMBER@service-networking.),且具備必要權限。

如果沒有服務帳戶,請建立一個:

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

將必要的 roles/servicenetworking.serviceAgent 角色授予服務帳戶:

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

後續步驟

建構記錄未按順序顯示

您執行了會輸出記錄檔的建構步驟,並注意到 stderr (錯誤) 記錄檔在 UI 中顯示的時間早於對應的 stdout (標準輸出內容) 記錄檔。記錄未按時間順序顯示。

這種排序方式是標準 Linux 和 Docker 串流緩衝行為。在非 TTY 環境 (例如建構容器) 執行程式碼時,stdout 會採用區塊緩衝 (延遲到緩衝區填滿),stderr 則維持無緩衝 (立即輸出)。

如要略過這個排序方法,並確保記錄嚴格排序,您必須在建構步驟的執行環境中,明確停用緩衝處理。

Python: 設定 PYTHONUNBUFFERED 環境變數: yaml steps: - name: 'python:3' env: ['PYTHONUNBUFFERED=1'] script: | python main.py

C/C++ 和 Bash 指令碼: 使用 stdbuf 指令強制執行行緩衝: yaml steps: - name: 'ubuntu' script: | stdbuf -oL ./your_binary

Java: Java 原生不支援使用旗標停用緩衝處理,但您可以在重要記錄陳述式後,強制程式碼立即清除: java System.out.println("Log message"); System.out.flush();