Error handling

When you build an add-in using the Excel JavaScript API, be sure to include error handling logic to account for runtime errors. Doing so is critical, due to the asynchronous nature of the API.

Note: For more information about the sync() method and the asynchronous nature of Excel JavaScript API, see Excel JavaScript API core concepts.

Best practices

Throughout the code samples in this documentation, you'll notice that every call to is accompanied by a catch statement to catch any errors that occur within the We recommend that you use the same pattern when you build an add-in using the Excel JavaScript APIs. (context) { 
  // Excel JavaScript API calls here

  // Await the completion of context.sync() before continuing.
  return context.sync()
    .then(function () {

API errors

When an Excel JavaScript API request fails to run successfully, the API returns an error object that contains the following properties:

  • code: The code property of an error message contains a string that is part of the OfficeExtension.ErrorCodes or Excel.ErrorCodes list. For example, the error code "InvalidReference" indicates that the reference is not valid for the specified operation. Error codes are not localized.

  • message: The message property of an error message contains a summary of the error in the localized string. The error message is not intended for end-user consumption; you should use the error code and appropriate business logic to determine the error message that your add-in shows to end-users.

  • debugInfo: When present, the debugInfo property of the error message provides additional information that you can use to understand the root cause of the error.

Note: If you use console.log() to print error messages to the console, those messages will only be visible on the server. End-users will not see those error messages in the add-in taskpane or anywhere in the host application.

Additional resources