Solução de problemas

Mesmo o desenvolvedor mais experiente raramente escreve o código corretamente na primeira tentativa, o que torna a solução de problemas uma parte importante do processo de desenvolvimento. Nesta seção, vamos abordar algumas técnicas que podem ajudar a encontrar, entender e depurar erros nos scripts.

Mensagens de erro

Quando o script encontra um erro, uma mensagem de erro é exibida. A mensagem é acompanhada por um número de linha usado para solução de problemas. Há dois tipos básicos de erros exibidos dessa maneira: erros de sintaxe e erros de execução.

Erros de sintaxe

Erros de sintaxe são causados por códigos que não seguem a gramática do JavaScript. Eles são detectados assim que você tenta salvar o script. Por exemplo, o snippet de código a seguir contém um erro de sintaxe:

function emailDataRow(rowNumber) {
  var sheet = SpreadsheetApp.getActiveSheet();
  var data = sheet.getDataRange().getValues();
  var rowData = data[rowNumber-1].join(" ";
  MailApp.sendEmail('john@example.com',
                    'Data in row ' + rowNumber,
                    rowData);
}

O problema de sintaxe aqui é um caractere ) ausente no final da quarta linha. Ao tentar salvar o script, você vai receber o seguinte erro:

) ausente após a lista de argumentos. (linha 4)

Esses tipos de erros geralmente são fáceis de resolver, porque são encontrados imediatamente e geralmente têm causas simples. Não é possível salvar um arquivo que contém erros de sintaxe, o que significa que apenas o código válido é salvo no projeto.

Erros de execução

Esses erros são causados pelo uso incorreto de uma função ou classe e só podem ser detectados depois que o script é executado. Por exemplo, o código abaixo causa um erro de execução:

function emailDataRow(rowNumber) {
  var sheet = SpreadsheetApp.getActiveSheet();
  var data = sheet.getDataRange().getValues();
  var rowData = data[rowNumber-1].join(" ");
  MailApp.sendEmail('john',
                    'Data in row ' + rowNumber,
                    rowData);
}

O código está formatado corretamente, mas estamos transmitindo o valor "joão" para o endereço de e-mail ao chamar MailApp.sendEmail. Como esse não é um endereço de e-mail válido, o seguinte erro é gerado ao executar o script:

E-mail inválido: john (linha 5)

O que torna esses erros mais difíceis de resolver é que, muitas vezes, os dados que você está transmitindo para uma função não são escritos no código, mas são extraídos de uma planilha, formulário ou outra fonte de dados externa. O uso das técnicas de depuração abaixo pode ajudar a identificar a causa desses erros.

Erros comuns

Confira abaixo uma lista de erros comuns e as causas deles.

Serviço chamado muitas vezes: <nome da ação>

Esse erro indica que você excedeu a cota diária de uma determinada ação. Por exemplo, esse erro pode ocorrer se você enviar muitos e-mails em um único dia. As cotas são definidas em níveis diferentes para contas de consumidor, de domínio e premium e estão sujeitas a alterações a qualquer momento sem aviso prévio do Google. Confira os limites de cota para várias ações na documentação de cota do Apps Script.

Servidor indisponível ou Ocorreu um erro no servidor. Tente novamente

Há algumas causas possíveis para esses erros:

  • Um servidor ou sistema do Google está temporariamente indisponível. Aguarde alguns instantes e tente executar o script novamente.
  • Há um erro no script que não tem uma mensagem de erro correspondente. Tente depurar o script e veja se você consegue isolar o problema.
  • Há um bug no Google Apps Script que está causando esse erro. Para instruções sobre como pesquisar e enviar relatórios de bugs, consulte Bugs. Antes de informar um novo bug, pesquise para ver se outras pessoas já o informaram.

É necessário ter autorização para realizar esta ação.

Esse erro indica que o script não tem a autorização necessária para ser executado. Quando um script é executado no Editor de script ou em um item de menu personalizado, uma caixa de diálogo de autorização é apresentada ao usuário. No entanto, quando um script é executado de um acionador, incorporado a uma página do Google Sites ou executado como um serviço, a caixa de diálogo não pode ser apresentada e esse erro é mostrado.

Para autorizar o script, abra o editor de script e execute qualquer função. A solicitacao de autorização vai aparecer para que você possa autorizar o projeto do script. Se o script tiver novos serviços não autorizados, você precisará autorizá-lo novamente.

Esse erro geralmente é causado por gatilhos que são acionados antes de serem autorizados pelo usuário. Se você não tiver acesso ao projeto de script (porque o erro está ocorrendo em um complemento que você usa, por exemplo), geralmente é possível autorizar o script usando o complemento novamente. Se um acionador continuar disparando e causando esse erro, remova seus acionadores:

  1. À esquerda do projeto do Apps Script, clique em Acionadores .
  2. À direita do acionador que você quer remover, clique em Mais > Excluir acionador.

Você também pode remover acionadores de complementos problemáticos desinstalando o complemento.

Acesso negado: DriveApp ou A política do domínio desativou apps de terceiros do Drive

Os administradores de Google Workspace domínios podem desativar a API Drive para o domínio, o que impede que os usuários instalem e usem apps do Google Drive. Essa configuração também impede que os usuários usem os complementos do Apps Script que usam o serviço do Drive ou o serviço avançado do Drive, mesmo que o script tenha sido autorizado antes da desativação da API Drive pelo administrador.

No entanto, se um complemento ou app da Web que usa o serviço do Drive for publicado para instalação em todo o domínio e for instalado pelo administrador para alguns ou todos os usuários no domínio, o script vai funcionar para esses usuários, mesmo que a API do Drive esteja desativada no domínio.

O script não tem permissão para receber a identidade do usuário ativo.

Indica que a identidade e o e-mail do usuário ativo não estão disponíveis para o script. Esse aviso resulta de uma chamada para Session.getActiveUser(). Também pode resultar de uma chamada para Session.getEffectiveUser() se o script estiver sendo executado em um modo de autorização diferente de AuthMode.FULL. Se esse aviso for sinalizado, as chamadas subsequentes para User.getEmail() vão retornar apenas "".

Há várias maneiras de resolver esse problema, dependendo do modo de autorização em que o script está sendo executado. O modo de autorização é exposto em funções acionadas como a propriedade authMode do e parâmetro do evento.

  • Em AuthMode.FULL, use Session.getEffectiveUser().
  • Em AuthMode.LIMITED, verifique se o proprietário autorizou o script.
  • Em outros modos de autorização, evite chamar qualquer um dos métodos.
  • Se você é um Google Workspace cliente que está recebendo esse aviso pela primeira vez de um gatilho instalável, verifique se ele está sendo executado como um usuário na sua organização.

A biblioteca está ausente

Se você adicionar uma biblioteca popular ao script, poderá receber uma mensagem de erro informando que ela está ausente, mesmo que a biblioteca esteja listada como uma dependência do script. O motivo pode ser que muitas pessoas estão acessando a biblioteca ao mesmo tempo. Para evitar esse erro, tente uma destas soluções:

  • Copie e cole o código da biblioteca no script e remova a dependência da biblioteca.
  • Copie o script da biblioteca e implante-o como uma biblioteca na sua conta. Atualize a dependência no script original para a nova biblioteca em vez da pública.

Ocorreu um erro porque uma versão da biblioteca ou da implantação está ausente. Código de erro Not_Found

Essa mensagem de erro indica uma das seguintes situações:

  • A versão implantada do script foi excluída. Para atualizar a versão implantada do script, consulte Editar uma implantação com versão.
  • A versão de uma biblioteca usada pelo script foi excluída. Para verificar qual biblioteca está faltando, ao lado do nome da biblioteca, clique em Mais > Abrir em uma nova guia. A biblioteca ausente exibe uma mensagem de erro. Depois de encontrar a biblioteca que precisa ser atualizada, faça uma das seguintes ações:
  • O script de uma biblioteca que seu script usa inclui outra biblioteca que usa uma versão excluída. Escolha uma destas opções:
    • Se você tiver acesso de edição à biblioteca usada pelo script, atualize a biblioteca secundária nesse script para uma versão existente.
    • Atualize a biblioteca para usar uma versão diferente. Consulte Atualizar uma biblioteca.
    • Remova a biblioteca do projeto e do código do script. Consulte Remover uma biblioteca.

Erro 400: invalid_scope ao chamar a API Google Chat com o serviço avançado

Se você encontrar Error 400: invalid_scope com a mensagem de erro Some requested scopes cannot be shown, significa que não especificou nenhum escopo de autorização no arquivo appsscript.json do projeto do Apps Script. Na maioria dos casos, o Apps Script determina automaticamente quais escopos um script precisa, mas, ao usar o serviço avançado do Chat, é necessário adicionar manualmente os escopos de autorização usados pelo script ao arquivo de manifesto do projeto do Apps Script. Consulte Como definir escopos explícitos.

Para resolver o erro, adicione os escopos de autorização apropriados ao arquivo appsscript.json do projeto do Apps Script como parte do array oauthScopes. Por exemplo, para chamar o método spaces.messages.create, adicione o seguinte:

"oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages.create"
]

As chamadas de UrlFetch para <URL> não são permitidas pelo seu administrador

Os administradores do Google Workspace podem ativar uma lista de permissões no Admin Console para controlar quais domínios externos você pode acessar pelo Apps Script.

Para resolver o erro, entre em contato com o administrador para adicionar o URL à lista de permissões.

Depuração

Nem todos os erros geram uma mensagem de erro. Pode haver um erro mais sutil em que o código está tecnicamente correto e pode ser executado, mas os resultados não são os esperados. Confira algumas estratégias para lidar com essas situações e investigar melhor um script que não está sendo executado da maneira esperada.

Logging

Durante a depuração, é útil registrar informações conforme um projeto de script é executado. O Google Apps Script tem dois métodos para registrar informações: o serviço de registro do Cloud e os serviços de registro e console mais básicos, integrados ao editor do Apps Script.

Consulte o guia de registro para mais detalhes.

Error Reporting

As exceções que ocorrem devido a erros de execução são registradas automaticamente usando o serviço de relato de erros do Google Cloud. Esse serviço permite pesquisar e filtrar mensagens de exceção criadas pelo projeto de script.

Para acessar o Error Reporting, consulte Conferir registros do Cloud e relatórios de erros no console do Google Cloud Platform.

Execuções

Toda vez que você executa um script, o Apps Script registra a execução, incluindo os registros do Cloud. Esses registros podem ajudar a entender quais ações o script executou.

Para conferir as execuções do script no projeto do Apps Script, clique em Execuções à esquerda.

Como verificar o status do serviço do Apps Script

Embora raros, às vezes serviços específicos do Google Workspace (como o Gmail ou o Drive) encontram problemas temporários que podem levar a interrupções no serviço. Quando isso acontece, os projetos do Apps Script que interagem com esses serviços podem não funcionar como esperado.

Para verificar se há uma falha temporária no serviço do Google Workspace, acesse o Painel de status do Google Workspace. Se houver uma interrupção, aguarde a resolução ou procure mais ajuda na Central de Ajuda do Google Workspace ou na documentação de Problemas conhecidos do Google Workspace.

Usar o depurador e os pontos de interrupção

Para localizar problemas no script, execute-o no modo de depuração. Quando executado no modo de depuração, um script é pausado quando atinge um ponto de interrupção, que é uma linha que você destacou no script e que pode ter um problema. Quando um script é pausado, ele mostra o valor de cada variável naquele momento, permitindo que você inspecione o funcionamento interno de um script sem precisar adicionar muitos comandos de registro.

Adicionar um ponto de interrupção

Para adicionar um ponto de interrupção, passe o cursor sobre o número da linha em que você quer adicionar o ponto. À esquerda do número da linha, clique no círculo. A imagem abaixo mostra um exemplo de um ponto de interrupção adicionado a um script:

Adicionar um ponto de interrupção

Executar um script no modo de depuração

Para executar o script no modo de depuração, clique em Debug na parte de cima do editor.

Antes de executar a linha com o ponto de interrupção, o script pausa e mostra uma tabela de informações de depuração. É possível usar essa tabela para inspecionar dados como os valores dos parâmetros e as informações armazenadas em objetos.

Para controlar como o script é executado, na parte de cima do painel do depurador, use os botões "Step in", "Step over" e "Step out". Elas permitem executar o script uma linha por vez e inspecionar como os valores mudam ao longo do tempo.

Problemas com várias Contas do Google

Se você estiver conectado a várias Contas do Google ao mesmo tempo, poderá ter problemas para acessar seus complementos e apps da Web. Não é possível fazer login múltiplo, ou fazer login em várias Contas do Google ao mesmo tempo, em projetos, complementos ou apps da Web do Apps Script.

  • Se você abrir o editor do Apps Script com login em mais de uma conta, o Google vai pedir que você escolha a conta que quer usar.

  • Se você abrir um app da Web ou um complemento e tiver problemas de login múltiplo, tente uma destas soluções:

    • Saia de todas as suas Contas do Google e faça login apenas na que tem o complemento ou app da Web que você quer acessar.
    • Abra uma janela anônima no Google Chrome ou uma janela de navegação privada equivalente e faça login na Conta do Google que tem o complemento ou o app da Web que você quer acessar.

Receber ajuda

A depuração de um problema usando as ferramentas e técnicas listadas acima pode resolver vários problemas, mas talvez você encontre alguns que exijam ajuda extra para serem resolvidos. Consulte nossa página de suporte para informações sobre onde fazer perguntas e informar bugs.