Solução de problemas

Mesmo o desenvolvedor mais experiente raramente escreve um código correto na primeira tentativa, o que torna a solução de problemas uma parte importante do processo de desenvolvimento. Esta seção aborda técnicas para encontrar, entender e depurar erros nos scripts.

Mensagens de erro

Quando o script encontra um erro, uma mensagem de erro aparece com um número de linha. Há dois tipos básicos de erros: erros de sintaxe e erros de execução.

Erros de sintaxe

Os erros de sintaxe ocorrem quando o código não segue a gramática do JavaScript e são detectados quando você salva o script. Por exemplo, o snippet 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 é um caractere ) ausente no final da linha 4. Quando você salva o script, o seguinte erro aparece:

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

Esses erros são encontrados imediatamente, o que facilita a solução de problemas. Somente códigos válidos são salvos no projeto.

Erros de execução

Os erros de execução ocorrem quando uma função ou classe é usada incorretamente e são detectados quando o script é executado. Por exemplo, o código a seguir 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);
}

Embora o código esteja formatado corretamente, "john" é um endereço de e-mail inválido. O seguinte erro é gerado:

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

Esses erros são desafiadores porque os dados geralmente são extraídos de fontes externas, como planilhas ou formulários. Use técnicas de depuração para identificar a causa.

Erros comuns

A seguir, confira uma lista de erros comuns e suas causas.

Serviço chamado muitas vezes: <action name>

Esse erro indica que você excedeu sua cota diária para uma ação, como enviar muitos e-mails. As cotas variam de acordo com o tipo de conta e estão sujeitas a alterações. Consulte os limites na documentação de cotas do Apps Script.

O servidor não está disponível ou Ocorreu um erro no servidor.Tente novamente.

As possíveis causas incluem:

• Um servidor do Google está temporariamente indisponível. Aguarde e tente novamente.
• Um erro no script não tem uma mensagem correspondente. Tente depurar para isolar o problema.
• Há um bug no Google Apps Script. Pesquise e registre relatórios de bugs em Bugs.

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

O script não tem a autorização necessária para ser executado. Quando um script é executado por um acionador ou como um serviço, uma caixa de diálogo de autorização não pode ser apresentada.

Para autorizar o script, abra o editor de scripts e execute qualquer função. Se o script usar novos serviços não autorizados, você precisará autorizá-lo novamente.

Os acionadores que são disparados antes da autorização ou após a expiração geralmente causam esse erro. Se um complemento causar isso, use-o novamente para autorizar. Remova os acionadores problemáticos:

1. No projeto do Apps Script, clique em Acionadores alarm.
2. Ao lado do acionador, clique em Mais more_vert > Excluir acionador.

Como alternativa, desinstale o complemento.

Permissões detalhadas também podem causar esses erros. Consulte a página de escopos de autorização para proteger as execuções de acionadores.

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

Os administradores do Google Workspace podem desativar a API Drive para o domínio, o que impede que os usuários usem apps do Drive ou complementos do Apps Script que usam o serviço do Drive.

Se um complemento ou app da Web for publicado para instalação em todo o domínio e instalado por um administrador, as funções de script vão funcionar mesmo que a API Drive esteja desativada.

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

A identidade e o e-mail do usuário ativo não estão disponíveis. Isso resulta de chamadas para Session.getActiveUser() ou Session.getEffectiveUser() em modos de autorização diferentes de AuthMode.FULL. Se o script for executado em um acionador, você poderá encontrar o modo de autorização na authMode propriedade do objeto de evento do Apps Script.

Solucione o problema com base no modo de autorização:

• Em AuthMode.FULL, considere usar Session.getEffectiveUser() em vez disso.
• 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ê for um cliente do Google Workspace que acabou de receber esse alerta de um acionador instalável, verifique se o acionador está sendo executado como um usuário na sua organização.

A biblioteca está ausente

Uma biblioteca poderá ser informada como ausente se muitas pessoas acessarem ela simultaneamente. Para resolver isso:

• Copie o código da biblioteca diretamente no script.
• Copie e implante a biblioteca da sua própria conta.
• Se a biblioteca não for necessária para o funcionamento do script, remova-a do projeto.

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

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

• A versão do script usada por uma implantação foi excluída. Para resolver isso, edite a implantação e selecione uma versão de script diferente.
• Uma versão da biblioteca usada pelo script foi excluída. Para resolver isso, no editor de scripts, em "Bibliotecas", encontre a biblioteca e atualize para uma versão diferente ou remova a biblioteca. Para atualizar, clique no número da versão e selecione uma versão diferente. Para remover, clique em Mais more_vert > Remover.
• Uma biblioteca inclui outra biblioteca, e a versão dessa biblioteca foi excluída. Para resolver isso, entre em contato com o autor da biblioteca ou use uma versão diferente da biblioteca que o script usa.

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, isso significa que você 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 que o script usa ao arquivo de manifesto do projeto do Apps Script. Consulte 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 da matriz oauthScopes. Por exemplo, para chamar o spaces.messages.create método, adicione o seguinte:

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

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

Os administradores do Google Workspace podem usar uma lista de permissões para controlar o acesso a domínios externos. Entre em contato com o administrador para adicionar o URL à lista de permissões.

Violação da política de permissões

Esse erro ocorre quando um aplicativo que usa HTMLService tenta executar APIs da Web que exigem permissões confidenciais, como navigator.mediaDevices.getUserMedia() para acesso à câmera ou ao microfone. O ambiente de sandbox do Apps Script restringe esses recursos para proteger a segurança do usuário.

Hospede a funcionalidade que exige essas permissões em um domínio separado (fora do Apps Script) e abra-o em uma nova janela ou guia. Em seguida, você pode postar os dados ou respostas capturados de volta no aplicativo do Apps Script, conforme mostrado neste exemplo.

function doGet(e) {
  return HtmlService.createHtmlOutputFromFile('Index')
      .setTitle('Media Devices Example');
}
function processCameraData(data) {
  Logger.log('Received data from client-side: ' + data);
  // Process data as needed
}

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
  </head>
  <body>
    <button id="open-camera">Open Camera in New Window</button>
    <script>
      document.getElementById('open-camera').addEventListener('click', function() {
        // URL for external domain handling camera access & posting data back.
        // External page uses getUserMedia & window.opener.postMessage(...).
        var externalUrl = 'https://your-external-domain.com/camera';
        window.open(externalUrl, 'cameraWindow', 'width=600,height=400');
      });

      // Listen for messages from the external window.
      window.addEventListener('message', function(event) {
        // Check event.origin to ensure message is from the expected source.
        if (event.origin !== 'https://your-external-domain.com') {
          return;
        }
        console.log('Data received from external window:', event.data);
        // Send data to server-side Apps Script.
        google.script.run.processCameraData(event.data);
      });
    </script>
  </body>
</html>

Depuração

Alguns erros são sutis e não acionam mensagens. Por exemplo, o código pode ser executado, mas os resultados são inesperados. Use as estratégias a seguir para investigar scripts que se comportam de maneira inesperada.

Logging

Registre informações à medida que um script é executado usando o serviço Cloud Logging ou os serviços Logger e console no editor de scripts.

Error Reporting

Para usar o Error Reporting no Google Cloud, use um projeto padrão gerenciado pelo usuário em vez de um projeto padrão.

Quando você usa um projeto padrão, os erros de execução são registrados automaticamente no Error Reporting do Google Cloud. Consulte os registros e relatórios de erros do Cloud no console do Google Cloud.

Execuções

O Google Apps Script registra todas as execuções, incluindo os registros do Cloud. Para visualizar as execuções, clique em Execuções playlist_play.

Como verificar o status do serviço

Verifique se há interrupções no serviço do Google Workspace no Painel de status do Google Workspace.

Usar o depurador e os pontos de interrupção

Para localizar problemas no script, você pode executá-lo 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 destacada no script que você acha 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 muitas instruções 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 de interrupção. À 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:

Executar um script no modo de depuração

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

Antes de executar a linha com o ponto de interrupção, o script é pausado e mostra uma tabela de informações de depuração. Você pode 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 "Entrar", "Passar" e "Sair". Eles permitem executar o script uma linha por vez e inspecionar como os valores mudam ao longo do tempo.

Erro: o código-fonte da linha atual não está disponível

Esse erro aparece quando um arquivo de depuração ativo não está disponível. O Google Apps Script não oferece suporte à exibição de scripts JavaScript (JS) gerados dinamicamente no editor de scripts, como aqueles gerados usando eval() e new Function(). Esses scripts são criados e executados no mecanismo V8, mas não são representados como arquivos independentes no editor. Se você entrar nesses scripts, esse erro vai ocorrer.

Por exemplo, considere o código a seguir:

function myFunction() {
  eval('a=2');
}

Quando eval() é invocado, o argumento é tratado como código JS e executado como um script criado dinamicamente no mecanismo V8. Se você entrar em eval(), esse erro vai aparecer. Se o script incluir um comentário //# sourceURL, o nome dele será mostrado na pilha de chamadas. Caso contrário, ele vai aparecer como uma entrada sem nome.

Apesar da mensagem de erro, a sessão de depuração permanece ativa, e a execução pode continuar. Para continuar, entre, saia ou retome a execução. No entanto, esse erro continua aparecendo enquanto a execução permanecer no escopo do script dinâmico. Depois que a execução sair do script dinâmico, a depuração vai continuar sem esse erro.

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 de script do Apps Script enquanto estiver logado em mais de uma conta, a solicitação do Google vai pedir que você escolha a conta que quer continuar.

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

  • Saia de todas as Contas do Google e faça login apenas na conta 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 app da Web que você quer acessar.

Receber ajuda

Acesse nossa página de suporte para fazer perguntas ou registrar bugs.