Troubleshoot deployment issues

If you run into problems deploying your app using the App Engine Admin API, this section lists error messages and suggestions for fixing each error.

The caller does not have permission to access project

The following error occurs when you deploy your app:

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

This error occurs if the account that you used to deploy your app does not have permission to deploy apps for the current project.

To resolve this issue, grant the App Engine Deployer (roles/appengine.deployer) role to the account. To see which account you used to deploy, do one of the following:

  • If you used the Google Cloud CLI to deploy, run the gcloud auth list command.
  • If you deployed from an IDE, view the settings for the Cloud Tools plugin.

Failed to fetch metadata from the registry

The following error occurs when you deploy your app:

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

This error occurs if you use the gcloud app deploy command from a service account that does not have the Storage Admin (roles/storage.admin) role.

To resolve this issue, grant the Storage Admin role to the service account:

  • To see which account you used, run the gcloud auth list command.
  • To learn why assigning only the App Engine Deployer (roles/appengine.deployer) role might not be sufficient in some cases, see App Engine roles.

Service accounts must have permissions on the image

The following error occurs when you deploy your app:

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

This error occurs for one of the following reasons:

Failed to create Cloud Build

The following error occurs when you deploy your app:

Failed to create cloud build: Permission denied

This error occurs if you use the gcloud app deploycommand from an account that does not have the Cloud Build Editor (roles/cloudbuild.builds.editor) role.

To resolve this issue, grant the Cloud Build Editor role to the service account that you are using to deploy your app.

To see which account you used, run the gcloud auth list command.

Permissions error fetching application

The following error occurs when you deploy your app:

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

If you are running Google Cloud CLI version 328 or later, the following error occurs when you deploy your app:

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.

This error occurs if the account that you used to deploy your app doesn't have the App Engine Deployer (roles/appengine.deployer) role.

To resolve this issue, verify that you have granted the App Engine Deployer role to the service account that you used to deploy your app; grant the role if the service account does not have it. To see which account you used to deploy, do one of the following:

  • If you used the Google Cloud CLI to deploy, run the gcloud auth list command.
  • If you deployed from an IDE, view the settings for the Cloud Tools plugin.

Deployment fails for new projects

You might see the following error when you deploy your app for the first time in a new project:

ERROR: (gcloud.app.deploy) Error Response: [13] Failed to create cloud build: com.google.net.rpc3.client.RpcClientException:..........invalid bucket "staging.PROJECT-ID.appspot.com"; service account [email protected] does not have access to the bucket

Various factors can cause this error, such as missing permissions, and changes to org policies.

To resolve this issue, verify that you have granted the Storage Admin (roles/storage.admin) role to the default service account. To grant the Storage Admin role, see Store build logs in a user-created bucket

If you have already granted the Storage Admin role, along with the other required roles based on different permission errors you encounter during deployment, and are still unable to deploy your app, it might be due to the following changes to org policies:

  • Starting in May 2024, Google Cloud enforces secure-by-default organization policies for all organization resources. This policy prevents App Engine from granting the Editor role to the App Engine default services accounts by default.

  • Starting in June 2024, Cloud Build has changed the default behavior for how Cloud Build uses service accounts in new projects. This change is detailed in Cloud Build Service Account Change. As a result of this change, new projects deploying versions for the first time may be using the default App Engine service account with insufficient permissions for deploying versions.

To resolve this issue, do the following:

Timed out waiting for the app infrastructure to become healthy

The following error occurs when you deploy your app:

Timed out waiting for the app infrastructure to become healthy

Various factors can cause this error, such as missing permissions, code errors, insufficient CPU or memory, or failed health checks. The error only occurs in the App Engine flexible environment.

To resolve this issue, rule out the following potential causes:

  1. Verify that you have granted the Editor (roles/editor) role to your default App Engine service account.

  2. Verify that you have granted the following roles to the service account that you use to run your application (usually the default service account, app-id@appspot.gserviceaccount.com):

  3. Grant the roles if the service account does not have them.

  4. If you are deploying in Shared VPC setup and passing instance_tag in app.yaml, refer to this section to fix the issue.

Permissions error when deploying a service with Serverless VPC Access Connector

The following error occurs when you deploy your app:

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

This error occurs when the user or service account that is trying to deploy the app with Serverless VPC Connector does not have the required permissions.

To resolve this issue, ensure the user or service account doing the deployment has Serverless VPC Access User and Compute Viewer IAM roles.

Invalid value error when deploying in a Shared VPC setup

The following error shows in Cloud Logging for Flex VM instances when you deploy your app:

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

This error is because of a current known issue where setting the instance_tag results in errors when creating instances.

To resolve the issue, remove the instance_tag field from your app.yaml file and redeploy.

Errors when deploying apps with three or less maximum instances

Apps deployed with max_instances set to three or less might experience unexpected errors or downtime. To resolve the issue, specify at least four maximum instances in your app.yaml file and redeploy.

Error when exceeding the limit on maximum instances

The following error occurs when you deploy your app:

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

There is a limit for maximum number of instances you can create per project. Requests to create additional instances fail if you exceed this limit.

To resolve this issue, set the value of max_instances in your app.yaml file to a value less than this limit or delete some services or versions to bring the sum of max_instances within the limit.

Build during deployment fails without errors in logs

The following error occurs when you are deploying your app:

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

Following the link in the error message shows that all build steps were successful. However, the app failed to build.

This problem occurs if you are using customer-managed encryption keys (CMEK) or you have set up a data retention policy for your staging.PROJECT_ID.appspot.com bucket.

To resolve this issue, change the following settings for your staging.PROJECT_ID.appspot.com bucket:

Build during deployment fails when running with NODE_ENV=development

This error might occur when you deploy a Node.js application. By default, the Node.js runtime will executenpm run build if a build script is detected in the package.json file.

This might cause unexpected behaivours like long-running builds, or out of memory errors.

Specify NODE_ENV=development in your app.yaml file to ensure the execution has all the required dependencies.

Despite the error, you can force production by specifying NODE_ENV: 'production' under build-env-variables in your app.yaml file:

  build_env_variables:
    NODE_ENV: 'production'

For more information see Executing custom build steps during deployment.