Troubleshooting

Even the most experienced developer rarely writes code correctly on the first try, making troubleshooting an important part of the development process. In this section we'll cover some techniques that can help you find, understand, and debug errors in your scripts.

Error messages

When your script encounters an error, an error message is displayed in a red bar at the top of the screen. The message is accompanied by a line number used for troubleshooting. There are two basic types of errors displayed in this way: syntax errors and runtime errors.

Syntax errors

Syntax errors are caused by writing code that doesn't follow the JavaScript grammar, and the errors are detected as soon as you try to save the script. For example, the following code snippet contains a syntax error:

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);
}

The syntax problem here is a missing ) character at the end of the fourth line. When you try to save the script you'll get the following error:

Missing ) after argument list. (line 4)

These types of errors are usually simple to troubleshoot, since they are found right away and typically have simple causes. You aren't able to save a file that contains syntax errors, meaning that only valid code is saved into your project.

Runtime errors

These errors are caused by using a function or class incorrectly, and can only be detected once the script has been run. For example, the following code causes a runtime error:

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);
}

The code is formatted correctly, but we are passing the value "john" for the email address when calling MailApp.sendEmail. Since this is not a valid email address the following error is thrown when running the script:

Invalid email: john (line 5)

What makes these errors more challenging to troubleshoot is that often the data you are passing into a function is not written in the code, but instead pulled from a spreadsheet, form, or other external data source. Using the debugging techniques below can help you to identify the cause of these errors.

Common errors

Below is a list of common errors and their causes.

Service invoked too many times: <action name>

This error indicates that you have exceeded your daily quota for a given action. For example, you might encounter this error if you send too many emails in a single day. The quotas are set at different levels for consumer, domain, and premier accounts and are subject to change at any time without a prior announcement by Google. You can view the quota limits for various actions in the Apps Script quota documentation.

Server not available. or Server error occurred, please try again.

There are a couple possible causes for these errors:

  • A Google server or system is temporarily unavailable. Wait for a few moments and try running the script again.
  • There is an error in your script that doesn't have a corresponding error message. Try debugging your script and see if you can isolate the problem.
  • There is a bug in Google Apps Script that is causing this error. For instructions on searching for and filing bug reports, see the Bugs. Before filing a new bug, search to see if others have already reported it.

Authorization is required to perform that action.

This error indicates that the script is lacking the authorization needed to run. When a script is run in the Script Editor or from a custom menu item an authorization dialog is presented to the user. However, when a script is run from a trigger, embedded with a Google Sites page, or run as a service, the dialog cannot be presented and this error is shown.

To authorize the script, open the Script Editor and run any function. The authorization prompt appears so you can authorize the script project. If the script contains new unauthorized services, you must re-authorize the script.

This error is frequently caused by triggers that are firing before the user has authorized them. If you don't have access to the script project (because the error is occurring for an add-on you use, for example), you can usually authorize the script by using the add-on again. If a trigger continues to fire and cause this error, you can access your triggers by doing the following:

  1. Select Edit > All your triggers in the Apps Script editor. The resulting dialog shows all active triggers running on your account.
  2. Find the offending trigger in the list.
  3. Click the clear icon next to the trigger name to remove it.
  4. Click Save to record the deletion.

You can also remove problematic add-on triggers by uninstalling the add-on.

Access denied: DriveApp or The domain policy has disabled third-party Drive apps

Administrators of G Suite domains have the ability to disable the Drive SDK for their domain, which prevents their users from installing and using Google Drive apps. This setting also prevents the users from being able to use Apps Script add-ons that use the Drive service or Advanced Drive Service (even if the script was authorized prior to the admin disabling Drive SDK).

However, if an add-on or web app using the Drive service is published for domain-wide installation and is installed by the administrator for some or all users in the domain, the script functions for those users even if the Drive SDK is disabled in the domain.

The script does not have permission to get the active user's identity.

Indicates that the active user's identity and email are not available to the script. This warning results from a call to Session.getActiveUser(). It can also result from a call to Session.getEffectiveUser() if the script is running in an authorization mode other than AuthMode.FULL. If this warning is signaled, subsequent calls to User.getEmail() only return "".

There are a number of ways to troubleshoot this warning, depending on the authorization mode the script is running under. The authorization mode is exposed in triggered functions as the authMode property of the e event parameter.

Debugging

Not all mistakes cause an error message to be displayed. There might be a more subtle error where the code is technically correct and can execute, but the results are not what you expect. Here are some strategies for handling such situations and further investigating a script that is not running the way you expect.

Logging

While debugging it's often helpful to record information as a script project executes. Google Apps Script has two methods for logging information: the Stackdriver logging service and the more basic Logger service that's built in to the Apps Script editor.

See the Logging guide for more details.

Stackdriver Error Reporting

You can enable Stackdriver Error Reporting the first time you select View > Stackdriver Logging or View > Stackdriver Error Reporting in a new script.

Once enabled, exceptions that occur because of runtime errors are automatically recorded using the Google Cloud Stackdriver service. This service lets you search and filter exception messages your script project creates. You can reach the Stackdriver Error Reporting interface by selecting View > Stackdriver Error Reporting in the Apps Script editor.

Execution transcript

Every time you run a script, Google Apps Script records an execution transcript, which is a record of each call to a Google Apps Script service that is made while the script runs. These transcripts can help you to understand which actions your script performed. To view the execution transcript click on View > Execution transcript in the menu bar after the script finishes running.

For example, the transcrpt for one execution might look like this:

[16-09-12 16:43:36:082 EDT] Starting execution
[16-09-12 16:43:36:087 EDT] SpreadsheetApp.getActiveSheet() [0 seconds]
[16-09-12 16:43:36:125 EDT] Sheet.getDataRange() [0.037 seconds]
[16-09-12 16:43:36:141 EDT] Range.getValues() [0.015 seconds]
[16-09-12 16:43:36:143 EDT] MailApp.sendEmail([john, Data in row 2, Cost 103.24]) [0 seconds]
[16-09-12 16:43:36:146 EDT] Execution failed: Invalid email: john (line 5, file "Code") [0.058 seconds total runtime]

This tells you that the MailApp.sendEmail method has failed and why. It also shows you that the last method to execute correctly was Range.getValues.

The execution transcript is reset each time the script is run or after some time has passed. There is also a limit on how many service calls can be recorded in one execution, so you may not be able to see every service call made.

Checking Apps Script service status

Although rare, sometimes specific G Suite services (such as Gmail or Drive) encounter temporary problems that can lead to service outages. When this occurs, Apps Script projects that interact with these services may not function as expected.

You can check if there is a G Suite service outage by viewing the G Suite Status Dashboard. If an outage is currently being experienced, you either wait for it to be resolved or seek additional help in the G Suite Help Center or the G Suite Known Issues documentation.

Using the debugger and breakpoints

The Script Editor lets you run a script in debug mode, which is specifically designed for locating problems. When run in debug mode a script pauses when it hits a breakpoint, which is a line you've highlighted in your script that you think may have a problem. When a script pauses it displays the value of each variable at that point in time, allowing you to inspect the inner workings of a script without having to add a lot of logging statements.

To add a breakpoint click on the line number for the line you want to pause at:

Setting a breakpoint

To run the script in debug mode click the bug icon (Bug icon) in the toolbar. Before the script runs the line with the breakpoint it pauses and display a table of debug information.

Pausing at a breakpoint

This table allows you to inspect the values of the parameters like row and email, as well as the information stored in the data object. Notice that the rowData variable doesn't have a value assigned yet, because the script paused before that line was executed.

When the script is paused, an extra set of buttons are displayed in the toolbar which allow you to control how the script is run. Using the "step in", "step over", and "step out" buttons you can run the script one line at a time, allowing you to inspect how values change over time.

Getting help

Debugging a problem using the tools and techniques listed above can solve a variety of problems, but there may be issues you run into that require some extra help to solve. See our Support page for information on where to ask questions and file bugs.

Send feedback about...

Apps Script
Apps Script
Need help? Visit our support page.