App Engine のエラーをトラブルシューティングする

デプロイ

このページでは、App Engine Admin API を使用したアプリのデプロイで問題が発生した場合に表示されるエラー メッセージと、そのエラーの修正方法に関するヒントについて説明します。

The caller does not have permission to access project

アプリをデプロイすると、次のエラーが発生します。

User EMAIL_ADDRESS does not have permission to access project PROJECT_ID (or it may not exist): The caller does not have permission

このエラーは、アプリのデプロイに使用したアカウントに現在のプロジェクトのアプリをデプロイする権限がない場合に発生します。

この問題を解決するには、アカウントに App Engine デプロイ担当者（roles/appengine.deployer）のロールを付与します。デプロイに使用したアカウントを確認するには、次のいずれかを行います。

  • Google Cloud CLI を使用してデプロイした場合は、gcloud auth list コマンドを実行します。
  • IDE からデプロイした場合は、Cloud Tools プラグインの設定を表示します。

Failed to fetch metadata from the registry

アプリをデプロイすると、次のエラーが発生します。

Failed to fetch metadata from the registry, with reason: generic::permission_denied

このエラーは、ストレージ管理者（roles/storage.admin）ロールを持たないサービス アカウントから gcloud app deploy コマンドを使用すると発生します。

この問題を解決するには、サービス アカウントにストレージ管理者のロールを付与します。

  • 使用したアカウントを確認するには、gcloud auth list コマンドを実行します。
  • App Engine デプロイ担当者（roles/appengine.deployer）のロールのみでは十分でない理由については、App Engine のロールをご覧ください。

Service accounts must have permissions on the image

アプリをデプロイすると、次のエラーが発生します。

The App Engine appspot and App Engine flexible environment service accounts must have permissions on the image IMAGE_NAME

このエラーは、次のいずれかの原因で発生します。

Failed to create cloud build

アプリをデプロイすると、次のエラーが発生します。

Failed to create cloud build: Permission denied

このエラーは、Cloud Build 編集者（roles/cloudbuild.builds.editor）ロールが割り当てられていないアカウントから gcloud app deploy コマンドを使用すると発生します。

この問題を解決するには、アプリのデプロイに使用しているサービス アカウントに Cloud Build 編集者ロールを付与します。

使用したアカウントを確認するには、gcloud auth list コマンドを実行します。

Permissions error fetching application

アプリをデプロイすると、次のエラーが発生します。

Permissions error fetching application apps/app_name. Please make sure you are using the correct project ID and that you have permission to view applications on the project

Google Cloud CLI バージョン 328 以降を実行している場合は、アプリをデプロイすると次のエラーが発生します。

Permissions error fetching application apps/app_name. Please
make sure that you have permission to view applications on the project and that
SERVICE_ACCOUNT has the App Engine Deployer (roles/appengine.deployer) role.

このエラーは、アプリのデプロイに使用したアカウントに App Engine デプロイ担当者（roles/appengine.deployer）ロールがない場合に表示されます。

この問題を解決するには、アプリのデプロイに使用したサービス アカウントに App Engine デプロイ担当者のロールが付与されていることを確認します。付与されていない場合は、このロールを付与します。デプロイに使用したアカウントを確認するには、次のいずれかを行います。

  • Google Cloud CLI を使用してデプロイした場合は、gcloud auth list コマンドを実行します。
  • IDE からデプロイした場合は、Cloud Tools プラグインの設定を表示します。

Timed out waiting for the app infrastructure to become healthy

アプリをデプロイすると、次のエラーが発生します。

Timed out waiting for the app infrastructure to become healthy

権限不足、コードエラー、CPU 性能やメモリ容量の不足、ヘルスチェックの失敗など、さまざまな要因が考えられます。このエラーは、App Engine フレキシブル環境でのみ発生します。

この問題を解決するには、次のように考えられる原因を排除します。

  1. 編集者（roles/editor）ロールがデフォルトの App Engine サービス アカウントに付与されていることを確認します。
  2. プロジェクトの組織のポリシーが外部 IP アドレスへのアクセスを制限していないか確認します。詳細については、App Engine フレキシブル環境の既知の問題をご覧ください。

  3. アプリケーションの実行に使用するサービス アカウント（通常はデフォルトのサービス アカウント app-id@appspot.gserviceaccount.com）に次のロールが付与されていることを確認します。

  4. サービス アカウントに上記のロールがない場合は、それを付与します。

  5. 共有 VPC 設定にデプロイし、app.yaml で instance_tag を渡す場合は、こちらのセクションを参照して問題を解決してください。

Permissions error when deploying a service with Serverless VPC Access Connector

アプリをデプロイすると、次のエラーが発生します。

Please ensure you have [compute.globalOperations.get] on the service project

このエラーは、サーバーレス VPC コネクタを使用してアプリをデプロイするユーザーまたはサービス アカウントに必要な権限がない場合に発生します。

この問題を解決するには、デプロイを行うユーザーまたはサービス アカウントに、サーバーレス VPC アクセス ユーザーのロールと Compute 閲覧者 IAM ロールを付与します。

Invalid value error when deploying in a Shared VPC setup

アプリをデプロイするときに Flex VM インスタンスの Cloud Logging に次のエラーが表示されます。

Invalid value for field 'resource.tags.items[1]': 'aef-instance'. Duplicate
tags are not allowed: aef-instance on compute.instances.insert

このエラーは、既知の問題（インスタンスの作成時に instance_tag を設定するとエラーが発生する）が原因で発生します。

この問題を解決するには、app.yaml から instance_tag フィールドを削除して再デプロイします。

最大インスタンス数が 3 以下のアプリをデプロイする際に発生するエラー

max_instances を 3 以下に設定してデプロイすると、予期しないエラーやダウンタイムが発生する可能性があります。この問題を解決するには、app.yaml に 4 以上の最大インスタンス数を指定して再デプロイします。

最大インスタンス数の上限を超えるとエラーが発生する

アプリをデプロイすると、次のエラーが発生します。

You may not have more than 'xx' total max instances in your project.

プロジェクトごとに作成できるインスタンスには上限があります。この上限を超えると、追加のインスタンスの作成リクエストは失敗します。

この問題を解決するには、app.yaml ファイルの max_instances の値をこの上限を下回る値に設定するか、一部のサービスまたはバージョンを削除して max_instances の合計が上限内に収まるようにします。

「compute.firewalls.list」権限が必要

共有 VPC ネットワークにアプリをデプロイすると、次のエラーが発生します。

Request to https://compute.googleapis.com/compute/v1/projects/projects/PROJECT_ID/global/firewalls?key failed, details: Required 'compute.firewalls.list' permission for 'projects/PROJECT_ID'

このエラーは、ホスト プロジェクトの次のサービス アカウントに Compute ネットワーク ユーザー（roles/compute.networkUser）ロールがない場合に発生します。

この問題を解決するには、ホスト プロジェクトの Google API サービス エージェントと App Engine フレキシブル環境サービス エージェント アカウントに Compute ネットワーク ユーザーのロールが付与されていることを確認してください。サービス アカウントに付与されていない場合は、ロールを付与します。

Build during deployment is failing without errors in build logs

アプリをデプロイすると、次のエラーが発生します。

ERROR: (gcloud.app.deploy) Cloud build failed. Check logs at https://console.cloud.google.com/cloud-build/builds/BUILD_ID?project=PROJECT_NUMBER Failure status: UNKNOWN: Error Response: [2] Build failed; check build logs for details

エラー メッセージのリンク先を確認すると、すべてのビルドステップが正常に完了していることが表示されていますが、アプリの作成に失敗しています。

この問題は、顧客管理の暗号鍵（CMEK）を使用している場合、または staging.PROJECT_ID.appspot.com バケットにデータ保持ポリシーを設定している場合に発生します。

この問題を解決するには、staging.PROJECT_ID.appspot.com バケットの以下の設定を変更します。

組織のポリシーの制約によりデプロイが失敗する

アプリをデプロイすると、次のエラーが発生します。

ERROR: (gcloud.app.deploy) Error Response: [13] An internal error occurred while processing task /app-engine-flex/....: Request to https://compute.googleapis.com/compute/[VERSSION]/[PROJECT_ID]/... failed, details: Constraint constraints/compute.disableGuestAttributesAccess violated for project [PROJECT_ID].

このエラーは、アプリのデプロイ時に組織のポリシーの制約 constraints/compute.disableGuestAttributesAccess が適用された場合に発生することがあります。このポリシーは、App Engine フレキシブル環境のすべてのアプリにデフォルトで適用されます。

この問題を解決するには、組織のポリシーの制約 constraints/compute.disableGuestAttributesAccess を無効にする必要があります。

既存のフレキシブル環境バージョンにデプロイするとエラーが発生する

既存の App Engine フレキシブル バージョンにデプロイすると、次のエラーが発生する可能性があります。

ERROR: (gcloud.app.deploy) Error Response: [9] An internal error occurred while
processing task /app-engine-flex/flex_await_healthy/flex_await_healthy

このエラーは、動作中の Docker イメージで異常なデプロイを更新しても、必ずしもデプロイが正常な状態になるわけではないことを示します。結果は、異常なデプロイによるインスタンスの状態によって異なります。エラーが発生しているにもかかわらず、適切な Docker イメージを指定すると、最終的にデプロイが正常な状態になる可能性があります。新しい Docker イメージで既存のバージョンを更新することはできますが、おすすめしません。

現在、バージョンでエラーが発生した場合はロールバックできません。

サービス提供

以降のセクションでは、アプリの初期化とサービス提供エラーについて説明します。

デフォルトのサービス アカウントでアプリを作成するときに発生する権限エラー

App Engine API を初めて有効にした後でアプリを作成すると、次のエラーで失敗します。

  • gcloud CLI:

    An internal error occurred while calling service consumer manager for service account.
Creating  App Engine application in project [PROJECT__ID] and [REGION]....failed. DEBUG: (gcloud.app.create) Error Response: [13] an internal error has occurred

  • リクエストログ:

    Service account creation is not allowed on this project.

  • コンソール:

    Error while initialising App Engine.

このエラーは、アプリの作成時に組織のポリシーの制約 constraints/iam.disableServiceAccountCreation が適用されたために発生することがあります。このポリシーにより、App Engine のデフォルトのサービス アカウント PROJECT_ID@appspot.gserviceaccount.com をプロビジョニングできなくなります。デフォルトのサービス アカウントはアプリの作成に必要であり、スキップできません。これは、バージョンごとのサービス アカウントを使用する場合にも当てはまります。

この問題を解決するには、組織のポリシーの制約 constraints/iam.disableServiceAccountCreation を一時的に削除して、App Engine のデフォルト サービス アカウントの作成とデプロイを許可する必要があります。その後、App Engine のデフォルトのサービス アカウントは削除できます。また、デプロイが正常に完了した後に作成したサービス アカウントに置き換えることもできます。

作成したサービス アカウントを使用している場合は、ロールの推奨事項の概要を確認して、サービス エージェント用に作成したサービス アカウントにトークン作成者のロールを提供するなど、権限を制限する方法を理解してください。

Nginx がアプリコンテナへの接続やコンタクトに失敗する

次のエラーは App Engine フレキシブル環境でのみ発生します。通常はエラーの直後に 502 エラーが返されます。

recv() failed (104: Connection reset by peer) while reading response header from upstream

このエラーは、nginx リバース プロキシ（nginx サイドカー）がアプリコンテナにアクセスできないことを示します。nginx ログの 502 エラーの終了タイミングを nginx.error ログのタイミングと比較できます。nginx.error に続けて 502 nginx エラーが発生している場合は、nginx 502 エラーが原因であると考えられます。

このエラーの多くは、アプリケーションの接続のキープアライブ タイムアウトが nginx のキープアライブ タイムアウトよりも短い場合に発生します。App Engine フレキシブル環境の nginx には 650 秒の keepalive_timeout が存在するため、アプリケーションは少なくともこの期間、接続を維持する必要があります。デフォルトでは、Node.js アプリケーションの keepAliveTimeout は 5,000 ミリ秒です。この場合、server.keepAliveTimeout を 700,000 ミリ秒に設定できます。

トラブルシューティングを行うには、VM インスタンスに接続して、アプリコンテナで実行中のコードから書き込まれたログを確認し、必要に応じてロギングを追加して根本原因を特定します。

メモリが不足している

App Engine フレキシブル環境で次のエラーが発生し、通常は 502 エラーが返されます。

kernel: [  133.706951] Out of memory: Kill process 4490 (java) score 878 or sacrifice child
kernel: [  133.714468] Killed process 4306 (java) total-vm:5332376kB, anon-rss:2712108kB, file-rss:0kB

このエラーは、App Engine がアプリケーションを終了したことを示します。

このエラーは、インスタンスのメモリが不足している場合に発生します。デフォルトでは、App Engine フレキシブル環境には 1 GB のメモリがあり、アプリケーション コンテナに使用できるメモリは 600 MB のみです。

トラブルシューティングを行うには、ログを確認し、メモリ不足のエントリがあるかどうかを確認します。memory_gb 構成を更新して再デプロイします。

受信リクエストを処理するオープン接続が不足している

待機中の接続の最大数がアクティブな接続数の 75% 以上の場合、アプリで 502 エラーが発生する可能性があります。

この問題を解決するには、Cloud Monitoring の指標でアクティブな接続と待機中の接続の最大数を確認し、待機中の接続の数を減らして、待機中の接続の最大数がアクティブな接続数の 75% 以下になるようにします。