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

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

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

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 バケットを作成します。手順については、ユーザーが作成したバケットへのビルドログの保存をご覧ください。

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

ビルドに使用しているサービスアカウントにタスクの実行に必要な権限が付与されていない場合は、次のようなエラーが表示されます。

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

このエラーに対処するには、サービスアカウントに必要な権限を付与します。次のページの情報を使用して、ビルドサービスアカウントに付与する権限を決定します。

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

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

Cloud Run Functions の使用時に次のエラーが表示される

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

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

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

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

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

次に、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 を確認する場合は、次の手順を行います。

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

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

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

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 を見て、権限またはエラーメッセージに記載されている権限を含む 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]

このエラーは、ビルドサービスアカウントに 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" } }

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

次のステップ

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