Edit

Troubleshoot Office Scripts

  • Article

As you develop Office Scripts, you may make mistakes. It's okay. You have the tools to help find the problems and get your scripts working perfectly.

Note

For troubleshooting advice specific to Office Scripts with Power Automate, see Troubleshoot Office Scripts running in Power Automate.

Platform limits and requirements

For a detailed list of limitations on the Office Scripts platform due to Excel, Power Automate, or other technologies, see Platform limits and requirements with Office Scripts.

Script errors

Office Scripts errors fall into one of two categories:

  • Compile-time errors or warnings
  • Runtime errors

Compile-time errors

Compile-time errors and warnings are initially shown in the Code Editor. These are shown by the wavy red underlines in the editor. They're also displayed under the Problems tab at the bottom of the Code Editor task pane. Selecting the error gives more details about the problem and suggests solutions. Compile-time errors should be addressed before running the script.

A compiler error shown in the Code Editor's hover text.

You may also see orange warning underlines and grey informational messages. These indicate performance suggestions or other possibilities where the script may have unintentional effects. Such warnings should be examined closely before dismissing them.

Runtime errors

Runtime errors happen because of logic issues in the script. This could be because an object used in the script isn't in the workbook, a table is formatted differently than anticipated, or some other slight discrepancy between the script's requirements and the current workbook. The following script generates an error when a worksheet named "TestSheet" is not present.

function main(workbook: ExcelScript.Workbook) {
  let mySheet = workbook.getWorksheet('TestSheet');

  // This will throw an error if there is no "TestSheet".
  mySheet.getRange("A1");
}

Some runtime errors are caused by exceeding the limits of the platform, such as trying to write too much data at once with Excel on the web. See Platform limits and requirements with Office Scripts for a full list of potential pitfalls.

Console messages

Both compile-time and runtime errors display error messages in the console when a script runs. They give a line number where the problem was encountered. Keep in mind that the root cause of any issue may be a different line of code than what is indicated in the console.

The following image shows the console output for the explicit any compiler error. Note the text [5, 16] at the beginning of the error string. This indicates the error is on line 5, starting at character 16. The Code Editor console displaying an explicit `any` error message.

The follow image shows the console output for a runtime error. Here, the script tries to add a worksheet with a the name of an existing worksheet. Again, note the "Line 2" preceding the error to show which line to investigate. The Code Editor console displaying an error from the `addWorksheet` call.

Console logs

Print messages to the screen with the console.log statement. These logs can show you the current value of variables or which code paths are being triggered. To do this, call console.log with any object as a parameter. Usually, a string is the easiest type to read in the console.

console.log("Logging myRange's address.");
console.log(myRange.getAddress());

Strings passed to console.log are displayed in the Code Editor's logging console, at the bottom of the task pane. Logs are found on the Output tab, though the tab automatically gains focus when a log is written.

Logs do not affect the workbook.

Automate tab not appearing or Office Scripts unavailable

The following steps should help troubleshoot any problems related to the Automate tab not appearing in Excel.

  1. Make sure your Microsoft 365 license includes Office Scripts.
  2. Ensure third-party cookies are enabled (when using Excel on the web).
  3. Ensure that your admin has not disabled Office Scripts in the Microsoft 365 admin center.
  4. Ensure that your admin has not configured a group policy to block Office Scripts (Windows only).
  5. Install WebView2 (Windows only).
  6. Ensure you're not logged in as an external or guest user to your tenant.

Important

When using Excel with Teams, Office Scripts are only supported in Teams on the web (not Teams for Windows, Mac, iOS, or Android).

Note

There is a known issue that prevents scripts stored in SharePoint from always appearing in the recently used list. This occurs when your admin turns off Exchange Web Services (EWS). Your SharePoint-based scripts are still accessible and usable through the file dialog.

Problems scheduling a script

Scheduling a script requires a business license for Microsoft 365. This is needed for the Power Automate flow that powers the scheduled script. Errors from this flow are shown when there are problems scheduling. You may need to manually update your flow in Power Automate, where it will be listed under My flows.

The following list shows common errors you might encounter.

  • The access token expiry UTC time is earlier than current UTC time.: Too much time has passed between signing into the service and scheduling the script. Reopen the script in the Code Editor or reload the workbook and try to schedule again.

Help resources

Stack Overflow is a community of developers willing to help with coding problems. Often, you'll be able to find the solution to your problem through a quick Stack Overflow search. If not, ask your question and tag it with the "office-scripts" tag. Be sure to mention you're creating an Office Script, not an Office Add-in.

See also