Resolver problemas do App Engine

Nesta página, descrevemos métodos de solução de problemas para erros que você pode encontrar ao usar o App Engine.

Consulte o Painel do Google Cloud Service Health para informações sobre incidentes que afetam os serviços do Google Cloud, como o App Engine.

Implantação

Se você tiver problemas para implantar seu app usando a API App Engine Admin, você vai encontrarmensagens de erro e sugestões para corrigir cada erro nesta seção.

O autor da chamada não tem permissão para acessar o projeto

O seguinte erro ocorre ao implantar o app:

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

Esse erro ocorrerá se a conta usada para implantar o app não tiver permissão para implantar apps no projeto atual.

Para resolver esse problema, conceda o papel de Implantador do App Engine (roles/appengine.deployer) à conta. Para ver qual conta você usou para implantar, siga um destes procedimentos:

  • Se você usou a Google Cloud CLI para implantar, execute o comando gcloud auth list.
  • Se você implantou em um ambiente de desenvolvimento integrado, veja as configurações do plug-in do Cloud Tools.

Falha ao buscar metadados pelo registro

O seguinte erro ocorre ao implantar o app:

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

Esse erro ocorrerá se você usar o comando gcloud app deploy de uma conta de serviço que não tem o papel Administrador do Storage (roles/storage.admin).

Para resolver esse problema, conceda o papel Administrador do Storage à conta de serviço:

  • Para ver qual conta você usou, execute o comando gcloud auth list.
  • Para saber por que apenas atribuir o papel de Implantador do App Engine (roles/appengine.deployer) pode não ser suficiente em alguns casos, consulte os Papéis do App Engine.

As contas de serviço precisam ter permissões na imagem.

O seguinte erro ocorre ao implantar o app:

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

Esse erro ocorre por um dos seguintes motivos:

Falha ao criar o Cloud Build

O seguinte erro ocorre ao implantar o app:

Failed to create cloud build: Permission denied

Esse erro ocorrerá se você usar o comando gcloud app deploy de uma conta que não tem o papel Editor do Cloud Build (roles/cloudbuild.builds.editor).

Para resolver esse problema, conceda o papel Editor do Cloud Build à conta de serviço que você está usando para implantar seu app.

Para ver qual conta você usou, execute o comando gcloud auth list.

Ocorreu um erro de permissão ao buscar o aplicativo

O seguinte erro ocorre ao implantar o 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

Se você estiver executando a versão 328 ou outra mais recente da Google Cloud CLI, o seguinte erro ocorrerá quando seu aplicativo for implantado:

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.

Esse erro ocorrerá se a conta que você usou para implantar o app não tiver o papel de Implantador do App Engine (roles/appengine.deployer).

Para resolver esse problema, verifique se você concedeu o papel de Implantador do App Engine à conta de serviço usada para implantar o app. Conceda o papel caso ela não tenha a conta de serviço. Para ver qual conta você usou para implantar, siga um destes procedimentos:

  • Se você usou a Google Cloud CLI para implantar, execute o comando gcloud auth list.
  • Se você implantou em um ambiente de desenvolvimento integrado, veja as configurações do plug-in do Cloud Tools.

Falha na implantação de novos projetos

Você pode ver o seguinte erro ao implantar seu aplicativo pela primeira vez em um novo projeto:

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 PROJECT-ID@appspot.gserviceaccount.com does not have access to the bucket

Vários fatores podem causar esse erro, como permissões ausentes e mudanças nas políticas da organização.

Para resolver esse problema, verifique se você concedeu o papel Administrador do Storage (roles/storage.admin) à conta de serviço padrão. Para conceder o papel Administrador do Storage, consulte Armazenar registros de versão em um bucket criado pelo usuário.

Se você já concedeu o papel de administrador do Storage, com as outras funções necessárias com base em diferentes erros de permissão encontrados durante a implantação, e ainda não consegue implantar seu aplicativo, isso pode ser devido às seguintes alterações nas políticas da organização:

  • Desde maio de 2024, o Google Cloud aplica políticas da organização com segurança por padrão a todos os recursos da organização. Isso impede que o App Engine conceda o papel Editor ao padrão do App Engine e contas de serviço do Google Cloud por padrão.

  • A partir de junho de 2024, o Cloud Build mudou o comportamento padrão de como o Cloud Build usa contas de serviço em novos projetos. Essa mudança está detalhada em Alteração da conta de serviço do Cloud Build. Como resultado dessa mudança, novos projetos que implantam versões pela primeira vez podem usar a conta de serviço do App Engine com permissões insuficientes para implantar versões.

Para resolver esse problema, faça o seguinte:

Tempo limite excedido para a infraestrutura do app se tornar íntegra

O seguinte erro ocorre ao implantar o app:

Timed out waiting for the app infrastructure to become healthy

Vários fatores podem causar esse erro, como permissões ausentes, erros de código, CPU ou memória insuficiente ou verificações de integridade com falha. O erro só ocorre no ambiente flexível do App Engine.

Para resolver esse problema, elimine as seguintes causas possíveis:

  1. Verifique se você concedeu o papel Editor (roles/editor) à conta de serviço padrão do App Engine.
  2. Verifique se a política da organização do seu projeto restringe o acesso a endereços IP externos. Para mais informações, consulte Problemas conhecidos do ambiente flexível do App Engine.

  3. Verifique se você concedeu os seguintes papéis à conta de serviço usada para executar o aplicativo (geralmente a conta de serviço padrão, app-id@appspot.gserviceaccount.com):

  4. Conceda os papéis caso a conta de serviço não os tenha.

  5. Se você estiver implantando na configuração da VPC compartilhada e transmitir instance_tag em app.yaml, consulte esta seção para corrigir o problema.

Erro de permissões ao implantar um serviço com o Conector VPC sem servidor

O seguinte erro ocorre ao implantar o app:

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

Esse erro ocorre quando o usuário ou a conta de serviço que está tentando implantar o aplicativo com o conector de VPC sem servidor não tem as permissões necessárias.

Para resolver esse problema, verifique se o usuário ou a conta de serviço que faz a implantação tem os papéis Usuário de acesso VPC sem servidor e IAM do visualizador do Compute.

Erro de valor inválido ao implantar em uma configuração de VPC compartilhada

O seguinte erro é exibido no Cloud Logging para instâncias de VM do Flex quando você implanta o aplicativo:

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

Esse erro ocorre devido a um problema atual em que a configuração de instance_tag resulta em erros durante a criação de instâncias.

Para resolver o problema, remova o campo instance_tag do arquivo app.yaml e implante novamente.

Erros ao implantar apps com até três instâncias ou menos

Apps implantados com max_instances definido como 3 ou menos podem apresentar erros ou inatividade inesperados. Para resolver o problema, especifique pelo menos quatro instâncias máximas no arquivo app.yaml e implante novamente.

Erro ao exceder o limite de instâncias máximas

O seguinte erro ocorre ao implantar o app:

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

Há um limite para o número máximo de instâncias que podem ser criadas por projeto. As solicitações para criar instâncias extras falharão se você exceder esse limite.

Para resolver esse problema, defina o valor de max_instances no seu arquivo app.yaml como um valor abaixo desse limite ou exclua alguns serviços ou versões para somar max_instances dentro do limite.

Erro ao reiniciar instâncias em versões em execução

O seguinte erro ocorre ao implantar o app:

error when restarting the instance under the running versions

Desde maio de 2024, o Google Cloud aplica a política da organização "Requer configuração do SO" para todos os novos projetos. Essa política exige que todas as instâncias de VM criadas em novos projetos tenham um VM Manager ativado. Nos projetos novos e atuais, essa restrição impede atualizações de metadados que desativem o VM Manager no nível do projeto e da instância.

Para resolver esse problema, desative a restrição da política da organização constraints/compute.requireOsConfig.

Permissão 'compute.firewalls.list' obrigatória

O seguinte erro ocorre quando você implanta o aplicativo em uma rede VPC compartilhada:

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'

Esse erro ocorrerá se as seguintes contas de serviço do projeto host não tiverem o papel de Usuário da rede do Compute (roles/compute.networkUser):

Para resolver esse problema, verifique se você concedeu o papel de usuário da rede do Compute às contas de serviço do agente de serviço de APIs do Google e de agente de ambiente do App Engine para o projeto host. Conceda o papel se as contas de serviço não tiverem esse papel.

A criação durante a implantação falha sem erros nos registros

O seguinte erro ocorre ao implantar o aplicativo:

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

Seguir o link na mensagem de erro mostra que todas as etapas da criação foram bem-sucedidas. No entanto, não foi possível criar o aplicativo.

Esse problema ocorre se você estiver usando chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês) ou tiver configurado uma política de retenção de dados para seu bucket staging.PROJECT_ID.appspot.com.

Para resolver esse problema, altere as seguintes configurações do bucket staging.PROJECT_ID.appspot.com:

A implantação falha devido a uma restrição de política da organização

O seguinte erro ocorre ao implantar um app:

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].

Esse erro pode ocorrer devido à aplicação da restrição da política da organização constraints/compute.disableGuestAttributesAccess ao implantar o app. Essa política é aplicada por padrão em todos os apps no ambiente flexível do App Engine.

Para resolver esse problema, desative a restrição da política da organização constraints/compute.disableGuestAttributesAccess.

Erros ao implantar em uma versão do ambiente flexível existente

O seguinte erro pode ocorrer ao implantar em uma versão flexível atual do 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

Esse erro indica que a atualização de uma implantação não íntegra com uma imagem Docker funcional nem sempre resulta em uma implantação íntegra. O resultado depende do estado das instâncias da implantação não íntegra. Apesar do erro, se você fornecer uma boa imagem Docker, a implantação poderá se tornar íntegra. Atualizar uma versão existente com uma nova imagem Docker, embora seja permitido, não é uma prática recomendada. Não há reversão em caso de falha da versão.

Erros de veiculação

Confira nas seções a seguir os erros de inicialização e veiculação do aplicativo.

Erro de permissão ao criar um app com a conta de serviço padrão

Quando você cria um aplicativo depois de ativar a API App Engine pela primeira vez, ele falha com os seguintes erros:

CLI da gcloud 

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

Solicitar registros 

Service account creation is not allowed on this project.

Console 

Error while initialising App Engine.

Esse erro pode ocorrer devido à aplicação da restrição da política da organização constraints/iam.disableServiceAccountCreation ao criar seu app. Esta política impede o provisionamento da conta de serviço padrão do App Engine PROJECT_ID@appspot.gserviceaccount.com.

Para resolver esse problema, remova temporariamente a restrição constraints/iam.disableServiceAccountCreation da política da organização para permitir a criação e a implantação da conta de serviço padrão do App Engine. A conta de serviço padrão é necessária para a criação do app e não pode ser ignorada. Isso também se aplica quando você usa uma conta de serviço por versão. A conta de serviço padrão do App Engine pode ser excluída ou substituída por uma conta de serviço criada após a implantação bem-sucedida.

Se você estiver usando uma conta de serviço criada, consulte a Visão geral de recomendações de papéis para entender como aplicar permissões de restrição, como fornecer um papel de criador de token na conta de serviço que você cria para o agente de serviço.

O Nginx falha ao se conectar ou entrar em contato com o contêiner do aplicativo

O seguinte erro ocorre apenas no ambiente flexível do App Engine e normalmente retorna com erros 502 imediatamente após o erro:

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

Esse erro indica que o proxy reverso nginx (arquivo secundário nginx) não consegue acessar o contêiner do app. Nos registros, é possível comparar o tempo de fechamento do erro 502 no registro nginx com o tempo do registro nginx.error. Um nginx.error seguido imediatamente por um erro nginx 502 é provavelmente a causa do erro nginx 502.

Esse erro geralmente ocorre quando o tempo limite de sinal de atividade da conexão do aplicativo é menor que o tempo limite do sinal de atividade do nginx. Como o nginx no ambiente flexível do App Engine tem keepalive_timeout de 650 segundos, os aplicativos precisam manter as conexões ativas por pelo menos esse período. Por padrão, os aplicativos Node.js têm um keepAliveTimeout de 5.000 milissegundos. Nesse caso, você pode definir server.keepAliveTimeout como 7.000.000 milissegundos.

Para resolver problemas, verifique os registros gravados pelo código em execução no contêiner do aplicativo. Para isso, conecte-se à instância de VM e adicione mais registros, se necessário, para encontrar a causa principal.

Memória insuficiente

O seguinte erro ocorre no ambiente flexível do App Engine e normalmente retorna com erros 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

Esse erro indica que o App Engine encerrou o aplicativo.

Esse erro ocorre quando a instância tem memória insuficiente. Por padrão, o ambiente flexível do App Engine tem 1 GB de memória, com apenas 600 MB disponíveis para o contêiner do aplicativo.

Para resolver o problema, verifique os registros e se você vê uma entrada "Sem memória". Atualize a configuração do memory_gb e reimplante.

Conexões abertas insuficientes para lidar com as solicitações recebidas

Os apps poderão encontrar um erro 502 se o número máximo de conexões de espera for igual ou maior que 75% do número de conexões ativas.

Para resolver o problema, verifique as Métricas do Cloud Monitoring para o número máximo de conexões ativas e em espera e diminuir o número de conexões de espera para garantir que o número máximo de conexões de espera seja menor ou igual a 75% do número de conexões ativas.