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. 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 few 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 remove your triggers by doing the following:
- At the left of the Apps Script project, click Triggers .
- At the right of the trigger you want to remove, click More > Delete trigger.
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 Google Workspace domains have the ability to disable the Drive API 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 API).
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 API 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.
- In
AuthMode.FULL, consider usingSession.getEffectiveUser()instead. - In
AuthMode.LIMITED, ensure that the owner has authorized the script. - In other authorization modes, avoid calling either method.
- If you are a Google Workspace customer newly experiencing this warning from an installable trigger, ensure that the trigger is running as a user within your organization.
Library is missing
If you add a popular library to your script, you might receive an error message stating that it's missing, even though the library is listed as a dependency for your script. The reason might be that too many people are accessing the library at the same time. To avoid this error, try one of the following solutions:
- Copy and paste the library's code into your script and remove the library dependency.
- Copy the library script and deploy it as a library from your account. Be sure to update the dependency in your original script to the new library instead of the public one.
Error occurred due to a missing library version or a deployment version. Error code Not_Found
This error message indicates one of the following:
- The deployed version of the script has been deleted. To update the deployed version of your script, see Edit a versioned deployment.
- The version of a library that the script uses has been deleted. To check which
library is missing, next to the library name, click
More
> Open in new tab. The missing library
gives an error message. After you find the library you need to update, take
one of the following actions:
- Update the library to use a different version. See Update a library.
- Remove the deleted library from your script project and code. See Remove a library.
- The script of a library that your script uses includes another
library that uses a deleted version. Take one of the following actions:
- If you have edit access to the library that your script uses, update the secondary library in that script to an existing version.
- Update the library to use a different version. See Update a library.
- Remove the library from your script project and code. See Remove a library.
Error 400: invalid_scope when calling Google Chat API with the advanced service
If you encounter Error 400: invalid_scope with the error message
Some requested scopes cannot be shown,
it means you haven't specified any authorization scopes in the
Apps Script project's appsscript.json file. In most cases,
Apps Script automatically determines what scopes a script needs,
but when you use the Chat advanced service, you must manually add
the authorization scopes that your script uses to your
Apps Script project's manifest file. See
Setting explicit scopes.
To resolve the error, add the appropriate authorization scopes
to the Apps Script project's appsscript.json file as part of
the oauthScopes array. For example, to call the
spaces.messages.create
method, add the following:
"oauthScopes": [
"https://www.googleapis.com/auth/chat.messages.create"
]
UrlFetch calls to <URL> are not permitted by your admin
Google Workspace administrators can turn on an allowlist in the admin console to control which external domains you can access through Apps Script.
To resolve the error, contact your administrator to have them add the URL to the allowlist.
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 Cloud logging service and the more basic Logger and console services that are built in to the Apps Script editor.
See the Logging guide for more details.
Error Reporting
Exceptions that occur because of runtime errors are automatically recorded using the Google Cloud Error Reporting service. This service lets you search and filter exception messages your script project creates.
To access Error Reporting, see View Cloud logs and error reports in the Google Cloud Platform console.
Executions
Every time you run a script, Apps Script makes a record of the execution, including the Cloud logs. These records can help you understand which actions your script performed.
To view the executions of your script in the Apps Script project, at the left, click Executions .
Checking Apps Script service status
Although rare, sometimes specific Google Workspace 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 Google Workspace service outage by viewing the Google Workspace Status Dashboard. If an outage is currently being experienced, you either wait for it to be resolved or seek additional help in the Google Workspace Help Center or the Google Workspace Known Issues documentation.
Use the debugger and breakpoints
To locate problems in your script, you can run it in debug mode. 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.
Add a breakpoint
To add a breakpoint, hover over the line number of the line you want to add the breakpoint to. At the left of the line number, click the circle. The below image shows an example of a breakpoint added to a script:
Run a script in debug mode
To run the script in debug mode, at the top of the editor click Debug.
Before the script runs the line with the breakpoint it pauses and displays a table of debug information. You can use this table to inspect data like the values of parameters and the information stored in objects.
To control how the script is run, at the top of the Debugger panel, use the "Step in", "Step over", and "Step out" buttons. These let you run the script one line at a time and inspect how values change over time.
Issues with multiple Google Accounts
If you're logged into multiple Google Accounts at the same time, you might have trouble accessing your add-ons and web apps. Multi-login, or being logged into multiple Google Accounts at once, isn't supported for Apps Script, add-ons, or web apps.
If you open the Apps Script editor while logged in to more than one account, Google prompts you to choose the account you want to proceed with.
If you open a web app or add-on and experience multi-login issues, try one of the following solutions:
- Log out of all your Google Accounts and only log in to the one that has the add-on or web app you want to access.
- Open an incognito window in Google Chrome, or an equivalent private browsing window, and log in to the Google Account that has the add-on or web app you want to access.
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.