ビルドエラーのトラブルシューティング

このページでは、ビルドの実行時に発生する可能性のある一般的なエラー メッセージに対するトラブルシューティングの方法と解決策を説明します。

ビルドログを確認しましたか？

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 編集者のロールとプロジェクト閲覧者の IAM ロールが付与されている必要があるためです。このエラーを解決するには、次のいずれかを行います。

• デフォルトのログバケットを使用して、ビルドを実行するユーザーにプロジェクト閲覧者のロールと Cloud Build 編集者のロールを付与します。この権限を付与する方法については、Cloud Build リソースへのアクセスを構成するをご覧ください。

• ログを保存するための独自の Cloud Storage バケットを作成します。手順については、ユーザーが作成したバケットへのビルドログの保存をご覧ください。

サービス アカウントの権限が付与されていないため、ビルドが失敗する

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 サービス アカウント
• IAM のロールについて
• Cloud Build サービス アカウントに権限を付与する

サービス アカウントの権限がないことを原因とするビルドエラーは、一般的に Cloud Build を使用してデプロイしようとした際に発生します。

Cloud Run Functions でデプロする際に権限が拒否されたエラーが発生する

Cloud Run の関数を使用しようとすると、次のエラーが表示されます。

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

このエラーに対処するには、Cloud Build サービス アカウントに Cloud Run Functions デベロッパーのロールを付与します。

Cloud Run Functions でデプロイする際に権限がないエラーが発生する

Cloud Run Functions でデプロイしようとすると、次のエラーが表示されます。

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

このエラーに対処するには、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 管理者のロールを付与します。

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 デベロッパーのロールを付与します。

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 権限がないことを示しています。このエラーを解決するには、Cloud Build Service Account IAM ロールを [PROJECT_NUMBER]@cloudbuild.gserviceaccount.com に付与します。このロールを付与する方法については、Cloud Build のサービス アカウントのアクセス権を構成するをご覧ください。

サービス エージェントの権限がないためビルドの送信に失敗する

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. 次に、Cloud Build サービス エージェントに roles/cloudbuild.serviceAgent IAM ロールを付与します。

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

サービス エージェントの権限の問題の原因となっている可能性がある IAM ID を確認する場合は、次の手順を行います。

1. Google Cloud コンソールでログ エクスプローラを開く:

   [ログ エクスプローラ] に移動

2. クエリ フィールドに次のテキストを入力します。

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

3. このクエリを使用した後にログエントリが表示された場合は、サービス エージェント（service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com）から権限が削除されているかどうかを確認します。削除されている場合は、そのログの protoPayload.authenticationInfo.principalEmail を見て、権限またはエラー メッセージに記載されている権限を含む roles/cloudbuild.serviceAgent ロールの削除に関連する IAM ID を確認します。

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 を制限するプロジェクトでは、push サブスクリプションを作成する機能が制限されます。境界内の制限付きサービスから 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 にコンテナ イメージを保存するために必要なストレージ管理者のロールが付与されていないことが原因で表示されます。

無効な 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 クライアント エラーが表示される場合は、ビルドログを確認し、エラーの理由に関する詳細情報が記載されているかどうかを確認します。クライアント エラーのよくある原因には、次のようなものがあります。

• 指定したソースの場所には commit することが必要な新しい情報が存在せず、作業用ツリーがクリーンである。この場合はソースコードの場所を確認して、もう一度ビルドをお試しください。
• リポジトリにビルド構成ファイルが含まれていない。これに該当する場合は、ビルド構成ファイルをリポジトリにアップロードし、ビルドを再度実行します。
• 誤ったトリガー 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 カスタマーケアにお問い合わせください。割り当てと上限の詳細については、割り当てと上限をご覧ください。

Docker レジストリからイメージを pull する際のタイムアウトの問題

実行後、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 コマンドが 1 時間以上実行されるビルドステップ（大きなイメージを Artifact Registry に push するなど）は、認証エラーで失敗する場合があります。 Cloud Build は認証トークンを 1 時間ごとに更新しますが、Docker がこれらの新しいトークンの取得に失敗し、認証の問題が発生する可能性があります。独自の存続期間を持つ独自のトークンを作成し、Docker コマンド用にファイル化して参照できます。

VPC ネットワークにピアリングされたプライベート プール内のキューに入れられたビルド

サービス プロデューサー ネットワークが独自の VPC ネットワークにピアリングされたプライベート プールでビルドを実行する場合、これら 2 つのネットワーク間のプライベート接続はそのまま維持することが重要です。プライベート プールが依存しているプライベート接続を削除すると、プライベート プールが切断されます。これは、最終的にタイムアウトするまでキューに残ったビルドとして表示されることがあります。したがって、プライベート接続を削除する場合は、このプライベート接続を使用してサービス プロデューサー ネットワークが独自の VPC ネットワークに接続されているプライベート プールも削除してください。

2 か月以上前の保留中のビルドを承認または拒否しようとする

2 か月以上経過した保留中のビルドを承認または拒否することはできません。これを試みると、次のようなエラー メッセージが表示されることがあります。

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

その場合は、新しいビルドを送信してみてください。

次のステップ

• ビルドログを管理する方法を確認する。