Outlook Add-in Troubleshooting Guide

Overview

This guide covers common issues with the Opensense Outlook Add-in, including deployment failures, signature behavior problems, and field editing errors. Issues are grouped by symptom. Start with the section that matches what you're seeing.

Known limitation: From switching on Outlook mobile

Switching the From address in Outlook mobile does not update the signature. Outlook mobile only passes the primary account context to the add-in API. This is a limitation of Outlook mobile add-in framework and is not configurable. The signature will always reflect the primary account on mobile.

Add-ins don’t get re-initialized when you toggle the “From” field in Outlook mobile.

Inconsistent add-in behavior

If you experience inconsistent behavior with auto-insertion, field edits, the multi-signature selector, or any other feature, start by resetting the cache in the Settings tab of the add-in pane. The current add-in version is displayed at the bottom of the pane on every screen.

Field edits not populating data

1. Confirm the user's data is syncing correctly from the directory source of truth and is populated in their Opensense user profile.

2. Rapidly clicking the Settings tab while it is loading can cause the add-in to enter a partial load state, preventing user parameters from fully syncing.

Signature not applying to the correct From address

If switching to an account on a different domain results in a blank signature preview or no signature being inserted, the alias domain is likely not recognized by Opensense. See the error below.

To resolve this, add the alias domain under Internal Domains in General Domain Settings in the Opensense portal. This ensures the add-in recognizes the account and applies the correct signature behavior across all associated domains.

Add-in disappears or fails to auto-insert (Outlook desktop)

Work through the steps below in order. Stop when the issue is resolved.

Step 1: Check Outlook on the Web (OWA) first

The add-in typically appears in OWA before syncing to the Outlook desktop application.

• If the add-in does not appear in OWA, the deployment has not propagated to the user's profile. Proceed to Step 5.

• If the add-in appears in OWA but not in the desktop app, proceed to Step 6 to clear the add-in cache.

Step 2: Clear the primary add-in cache

1. Close Outlook completely and confirm it is not running in the background.

2. Open File Explorer (Windows key + E).

3. Click the address bar, paste %localappdata%\Microsoft\Outlook, and press Enter.

4. Right-click the HubAppFileCache folder, select Rename, and append _old to the name (for example: HubAppFileCache_old).

5. Restart Outlook and check whether the add-in appears.

Step 3: Clear the secondary cache

1. Close Outlook again.

2. Open File Explorer and navigate to %localappdata%\Microsoft\Office\16.0.

3. Rename the Wef folder to Wef_old.

4. Restart Outlook.

Step 4: Switch to the alternate add-in format

If clearing both caches does not resolve the issue, use the Registry Editor to switch Outlook to an older add-in format.

1. Close Outlook and all other Office applications.

2. Press Windows key + R, type regedit, and press Enter. Click Yes if prompted by User Account Control.

3. In the left pane, navigate to: HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Common\ExperimentEcs\Overrides. If the Overrides key does not exist, right-click ExperimentEcs, select New > Key, and name it Overrides.

4. For each of the following, right-click in the right pane, select New > String Value, and enter the name and data exactly as shown:    

   • Name: Microsoft.Office.OEP.EwsManifestsDisabled / Data: false

   • Name: Microsoft.Office.OEP.MosExtensionsEnabled / Data: false

   • Name: Microsoft.Office.OEP.MosProviderEnabled / Data: false

5. Close the Registry Editor and start Outlook. Wait approximately one minute, then open a new compose window to confirm the add-in appears in the ribbon.

Step 5: Enable debugging for escalation

If the issue persists after completing Steps 1 through 3, enable debugging to generate a log file for your IT team or for submission to Microsoft support.

1. Press the Windows key, type regedit, and press Enter. Click Yes if prompted.

2. In the left pane, navigate to HKEY_CURRENT_USER > Software > Microsoft > Office > 16.0 > WEF.

3. Right-click the WEF folder, select New > Key, and name it Developer.

4. Right-click the Developer folder, select New > Key, and name it 3e422b9b-5137-4812-8f36-c9d3680e2b13.

5. Inside that key, create two DWORD (32-bit) values:    

   • Name: DebuggerPort / Value (Hexadecimal): 2407

   • Name: UseDirectDebugger / Value (Hexadecimal): 1

6. Navigate back up to the WEF folder. Right-click in the right pane, select New > String Value, and name it RuntimeLogging.

7. Double-click RuntimeLogging and set the value to C:\Users\YourUsername\OfficeAddins.log.txt, replacing YourUsername with your actual Windows username.

8. Close the Registry Editor and restart Outlook. The log file will be generated at the path you specified and can be shared with your IT team or submitted with a Microsoft support ticket.

Add-in not deploying via Microsoft Centralized Deployment

If the add-in is not appearing for users after being assigned via Centralized Deployment, work through the following steps in order.

Step 1: Allow time for Microsoft 365 sync

Microsoft 365 can take up to 72 hours to sync add-in assignments after deployment. Before troubleshooting further, confirm how long it has been since the add-in was assigned. If it has been less than 72 hours, wait and check again before proceeding.

Step 2: Verify deployment status in Microsoft 365 Admin Center

1. Go to Microsoft 365 Admin Center > Settings > Integrated Apps.

2. Locate the Opensense Outlook Add-in and confirm the deployment status is Active.

3. Confirm the affected users are assigned to a supported group.

Step 3: Confirm group assignments

Microsoft does not support nested groups for add-in deployment. Users must be directly assigned to a top-level group.

• If users are in a nested group, move them to a top-level Microsoft 365 group and reattempt deployment.

• If the group is dynamic, confirm the user meets the membership criteria.

See Microsoft's Centralized Deployment FAQ for further details on group targeting.

Step 4: Check Outlook on the Web (OWA)

The add-in typically appears in OWA before syncing to the Outlook desktop application.

• If the add-in does not appear in OWA, the deployment has not propagated to the user's profile. Proceed to Step 5.

• If the add-in appears in OWA but not in the desktop app, proceed to Step 6 to clear the add-in cache.

Step 5: Regrant admin consent

If a user was previously assigned the add-in but it never appeared, their profile may be in a stuck state.

1. Remove the user from the add-in's deployment scope.

2. Wait 30 to 60 minutes for Microsoft 365 to queue the removal.

3. Re-add the user to the scope.

4. Go to Azure AD Admin Center > Enterprise Applications, find Opensense Email Signatures, and select Permissions > Grant Admin Consent for the organization.

Step 6: Clear the Microsoft add-in cache

Windows

1. Close Outlook.

2. Open File Explorer and navigate to %LOCALAPPDATA%\Microsoft\Office\16.0\Wef.

3. Delete the contents of the Wef folder.

4. Restart Outlook.

Mac

1. Quit Outlook.

2. Open Terminal and run: rm -rf ~/Library/Containers/com.microsoft.Outlook/Data/Library/Application\ Support/Microsoft/Office/Wef

3. Restart Outlook.

Still having issues?

If the add-in has not appeared after 72 hours and all steps above have been completed, contact both MicrosoftMic and Opensense support.

Related articles

• Outlook Add-in Overview

• Outlook Add-in Routed Key Behaviors

• Outlook Add-in Domain Settings with Scenarios and Best Practices

• Opensense Add-in Integration with GCC High Environments