Edit

Troubleshoot event-based and spam-reporting add-ins

  • Article

As you develop your event-based or spam-reporting (preview) add-in, you may encounter issues, such as your add-in not loading or an event not occurring. The following sections provide guidance on how to troubleshoot your add-in.

Review feature prerequisites

Check manifest and JavaScript requirements

  • Ensure that the following conditions are met in your add-in's manifest.

    • Verify that your add-in's source file location URL is publicly available and isn't blocked by a firewall. This URL is specified in the SourceLocation element of the XML manifest or the "extensions.runtimes.code.page" property of the unified manifest for Microsoft 365.

    • Verify that the <Runtimes> element (XML manifest) or "extensions.runtimes.code" property (unified manifest) correctly references the HTML or JavaScript file containing the event handlers. Classic Outlook on Windows uses the JavaScript file during runtime, while Outlook on the web, on new Mac UI, and new Outlook on Windows (preview) use the HTML file. For an example of how this is configured in the manifest, see the "Configure the manifest" section of Automatically set the subject of a new message or appointment.

      For classic Outlook on Windows, you must bundle all your event-handling JavaScript code into this JavaScript file referenced in the manifest. Note that a large JavaScript bundle may cause issues with the performance of your add-in. We recommend preprocessing heavy operations, so that they're not included in your event-handling code.

  • Verify that your event-handling JavaScript file referenced by the Outlook client on Windows calls Office.actions.associate. This ensures that the event handler name specified in the manifest is mapped to its JavaScript counterpart.

    Tip

    If your add-in has only one JavaScript file referenced by Outlook on the web, on Windows (classic and new (preview)), and on Mac, it's recommended to check on which platform the add-in is running to determine when to call Office.actions.associate, as shown in the following code.

    if (Office.context.platform === Office.PlatformType.PC || Office.context.platform == null) {
  Office.actions.associate("onNewMessageComposeHandler", onNewMessageComposeHandler);
  Office.actions.associate("onNewAppointmentComposeHandler", onNewAppointmentComposeHandler);
}

  • The JavaScript code of event-based and spam-reporting add-ins that run in Outlook on Windows only supports ECMAScript 2016 and earlier specifications. Some examples of programming syntax to avoid are as follows.

    • Avoid using async and await statements in your code. Including these in your JavaScript code will cause the add-in to time out.
    • Avoid using the conditional (ternary) operator as it will prevent your add-in from loading.

    If your add-in has only one JavaScript file referenced by Outlook on the web, on Windows (classic and new (preview)), and on Mac, you must limit your code to ECMAScript 2016 to ensure that your add-in runs in Outlook on Windows. However, if you have a separate JavaScript file referenced by Outlook on the web, on Mac, and new Outlook on Windows (preview), you can implement a later ECMAScript specification in that file.

Debug your add-in

  • As you make changes to your add-in, be aware that:

    • If you update the manifest, remove the add-in, then sideload it again. If you're using Outlook on Windows, you must also close and reopen Outlook.
    • If you make changes to files other than the manifest, close and reopen the Outlook client on Windows or on Mac, or refresh the browser tab running Outlook on the web.
    • If you're still unable to see your changes after performing these steps, clear your Office cache.

  • As you test your add-in in Outlook on Windows:

    • For event-based add-ins, check Event Viewer for any reported add-in errors.

      1. In Event Viewer, select Windows Logs > Application.
      2. From the Actions panel, select Filter Current Log.
      3. From the Logged dropdown, select your preferred log time frame.
      4. Select the Error checkbox.
      5. In the Event IDs field, enter 63.
      6. Select OK to apply your filters.

      A sample of Event Viewer's Filter Current Log settings configured to only show Outlook errors with event ID 63 that occurred in the last hour.

    • Verify that the bundle.js file is downloaded to the following folder in File Explorer. Replace text enclosed in [] with your applicable information.

      %LOCALAPPDATA%\Microsoft\Office\16.0\Wef\{[Outlook profile GUID]}\[Outlook mail account encoding]\Javascript\[Add-in ID]_[Add-in Version]_[locale]

      Tip

      If the bundle.js file doesn't appear in the Wef folder, try the following:

  • As you test your add-in in Outlook on Windows or Mac, enable runtime logging to identify possible manifest and add-in installation issues. For guidance on how to use runtime logging, see Debug your add-in with runtime logging.

  • Set breakpoints in your code to debug your add-in. For platform-specific instructions, see Debug event-based and spam-reporting add-ins.

Seek additional help

If you still need help after performing the recommended troubleshooting steps, open a GitHub issue. Include screenshots, video recordings, or runtime logs to supplement your report.

See also