Debug Office Add-ins on a Mac

Because add-ins are developed using HTML and JavaScript, they are designed to work across platforms, but there might be subtle differences in how different browsers render the HTML. This article describes how to debug add-ins running on a Mac.

Important

Debugging add-ins with Office on Mac is only possible if Office is installed on the Mac from Office.com, not the Apple app store.

Debugging with Safari Web Inspector on a Mac

If you have add-in that shows UI in a task pane or in a content add-in, you can debug an Office Add-in using Safari Web Inspector.

To be able to debug Office Add-ins on Mac, you must have Mac OS High Sierra AND Mac Office Version 16.9.1 (Build 18012504) or later. If you don't have an Office on Mac build, you might qualify for a Microsoft 365 E5 developer subscription through the Microsoft 365 Developer Program; for details, see the FAQ. Alternatively, you can sign up for a 1-month free trial or purchase a Microsoft 365 plan.

To start, open a terminal and set the OfficeWebAddinDeveloperExtras property for the relevant Office application as follows:

• defaults write com.microsoft.Word OfficeWebAddinDeveloperExtras -bool true

• defaults write com.microsoft.Excel OfficeWebAddinDeveloperExtras -bool true

• defaults write com.microsoft.Powerpoint OfficeWebAddinDeveloperExtras -bool true

• defaults write com.microsoft.Outlook OfficeWebAddinDeveloperExtras -bool true

  Important

  Mac App Store builds of Office do not support the OfficeWebAddinDeveloperExtras flag.

Then, open the Office application and sideload your add-in. Right-click the add-in and you should see an Inspect Element option in the context menu. Select that option and it will pop the Inspector, where you can set breakpoints and debug your add-in.

Note

If you're trying to use the inspector and the dialog flickers, update Office to the latest version. If that doesn't resolve the flickering, try the following workaround.

1. Reduce the size of the dialog.
2. Choose Inspect Element, which opens in a new window.
3. Resize the dialog to its original size.
4. Use the inspector as required.

Clearing the Office application's cache on a Mac

Add-ins are often cached in Office on Mac for performance reasons. Normally, the cache is cleared by reloading the add-in. If more than one add-in exists in the same document, the process of automatically clearing the cache on reload might not be reliable.

Use the personality menu to clear the cache

You can clear the cache by using the personality menu of any task pane add-in. However, because the personality menu isn't supported in Outlook add-ins, you can try the option to clear the cache manually if you're using Outlook.

• Choose the personality menu. Then choose Clear Web Cache.

  Note

  You must run macOS Version 10.13.6 or later to see the personality menu.

  

Clear the cache manually

You can also clear the cache manually by deleting the contents of the ~/Library/Containers/com.Microsoft.OsfWebHost/Data/ folder. Look for this folder via terminal.

Note

If that folder doesn't exist, check for the following folders via terminal and if found, delete the contents of the folder.

• ~/Library/Containers/com.microsoft.{host}/Data/Library/Caches/ where {host} is the Office application (e.g., Excel)
• ~/Library/Containers/com.microsoft.{host}/Data/Library/Application Support/Microsoft/Office/16.0/Wef/ where {host} is the Office application (e.g., Excel)
• ~/Library/Containers/com.microsoft.Office365ServiceV2/Data/Caches/com.microsoft.Office365ServiceV2/
• ~/Library/Containers/com.microsoft.Office365ServiceV2/Data/Library/Caches/com.microsoft.Office365ServiceV2/

To look for these folders via Finder, you must set Finder to show hidden files. Finder displays the folders inside the Containers directory by product name, such as Microsoft Excel instead of com.microsoft.Excel.