Add-in Troubleshooting Guide

  • Updated on Oct 9, 2025
  • Published on Apr 29, 2025
  • 7 minute(s) read
  • corey smith
  • aZ
 Prev Next

Overview

This guide provides step-by-step solutions for common issues with the Opensense Outlook Add-in, covering installation, deployment, permissions, signature behavior, and functionality errors. Whether the add-in is missing, not applying signatures correctly, or experiencing sync issues, this resource helps diagnose and resolve problems efficiently. Use this guide to ensure a smooth experience and proper configuration of the add-in within Microsoft Outlook.

Account Switching on Outlook Mobile

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

    • Outlook mobile only passes the primary account context to the add-in API. Even if you switch to a different alias or profile, the add-in still thinks you’re sending as the primary identity.

    • Because of that, the add-in doesn’t fetch or render the correct signature for the switched “From” identity. This is a limitation of Outlook mobile’s add-in framework today. The add-in does not re-trigger a signature insert event when the “From” field changes.

Cross-Domain Account Switching

  • If you switch to an account on another domain (different from your primary) and notice that the add-in signature preview is blank or that a signature is not being inserted, this is typically due to domain configuration.

    • To resolve this, each alias domain must be added under Internal Domains within the General Domain Settings in Opensense. This ensures the add-in correctly recognizes the account and applies the proper signature behavior across all associated domains.

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 within the Settings tab of the add-in pane. The current add-in version is displayed at the bottom of the pane on every screen. Refer to the screenshot below for an overview.

Field Edits Not Populating Data

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

  2. Rapidly clicking on the Settings tab while it is loading may cause the add-in to enter a partial load state, preventing user parameters from fully syncing. DO NOT update fields if all are blank. Instead, reload the add-in by clicking back to the Signatures tab, allow it to fully load, and then navigate to the Settings tab.

Outlook Add-in Disappears or Fails to Auto-Insert on the Outlook Desktop Application

Follow these steps to fix the issue:

Step 1: Clear the add-in cache

  1. Close Outlook completely (make sure it's not running in the background)

  2. Open File Explorer by pressing the Windows key + E on your keyboard

  3. Navigate to the cache folder:

    • Click in the address bar at the top of File Explorer

    • Copy and paste this path: %localappdata%\Microsoft\Outlook

    • Press Enter

  4. Rename the folder:

    • Right-click on the HubAppFileCache folder

    • Select "Rename"

    • Add "_old" to the end of the name (example: HubAppFileCache_old)

    • Press Enter

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

Step 2: Clear the secondary cache (if needed)

If renaming the first folder didn't resolve the issue, repeat the process with a second cache folder:

  1. Close Outlook again

  2. Open File Explorer (Windows key + E)

  3. Navigate to: %localappdata%\Microsoft\Office\16.0

  4. Rename the Wef folder to Wef_old

  5. Restart Outlook

Step 3: Switch to the alternate add-in format (if needed)

If clearing both caches doesn't help, you can switch Outlook to use an older add-in format:

  1. Close Outlook and all other Office programs (Word, Excel, PowerPoint, etc.)

  2. Open the Windows Registry Editor:

    • Press the Windows key + R on your keyboard

    • Type regedit and press Enter

    • Click "Yes" if prompted by User Account Control

  3. Navigate to the correct location:

    • In the left pane, expand the folders to reach: HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Common\ExperimentEcs\Overrides

    • If the Overrides folder doesn't exist, right-click on ExperimentEcs, select "New" > "Key", and name it Overrides

  4. Add three new registry values: For each of the following, right-click in the right pane, select "New" > "String Value", and enter the exact name and data:

    • 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

  6. Start Outlook and wait about one minute for the add-in to load. You may need to open a new email to see the add-in button appear in the ribbon.Enabling Debugging for the Office Add-In (Windows)

If you continue to encounter inconsistent behaviors with the add-in on Windows, you can enable debugging. This is useful for troubleshooting with our engineering team or when submitting a Microsoft support ticket.

Enable Debugging for Add-in Troubleshooting

Follow these steps to enable debugging mode, which will help collect diagnostic information for your IT team or Microsoft support:

Step 1: Open the Registry Editor

  1. Press the Windows key on your keyboard

  2. Type regedit and press Enter

  3. Click "Yes" if prompted by User Account Control

Step 2: Navigate to the add-in settings location

  1. In the left pane of the Registry Editor, expand the folders in this order:

    • HKEY_CURRENT_USER

    • Software

    • Microsoft

    • Office

    • 16.0

    • WEF

Step 3: Create the debugging configuration

  1. Create the Developer folder:

    • Right-click on the WEF folder

    • Select "New" > "Key"

    • Name it Developer

  2. Create the add-in identifier folder:

    • Right-click on the Developer folder you just created

    • Select "New" > "Key"

    • Name it 3e422b9b-5137-4812-8f36-c9d3680e2b13

  3. Add the debugger port setting:

    • Right-click in the right pane (inside the 3e422b9b-5137-4812-8f36-c9d3680e2b13 folder)

    • Select "New" > "DWORD (32-bit) Value"

    • Name it DebuggerPort

    • Double-click on DebuggerPort

    • Select "Hexadecimal"

    • Enter 2407 in the Value data field

    • Click OK

  4. Add the direct debugger setting:

    • Right-click in the right pane again

    • Select "New" > "DWORD (32-bit) Value"

    • Name it UseDirectDebugger

    • Double-click on UseDirectDebugger

    • Select "Hexadecimal"

    • Enter 1 in the Value data field

    • Click OK

Step 4: Enable runtime logging

  1. In the left pane, click on the WEF folder (go back up two levels from where you are)

  2. Right-click in the right pane

  3. Select "New" > "String Value"

  4. Name it RuntimeLogging

  5. Double-click on RuntimeLogging

  6. Enter the log file path: C:\Users\YourUsername\OfficeAddins.log.txt

    • Important: Replace YourUsername with your actual Windows username

    • To find your username, open File Explorer and look at the path shown—it will be C:\Users\YourUsername

  7. Click OK

Step 5: Close and restart

  1. Close the Registry Editor

  2. Restart Outlook

  3. The add-in will now generate a log file at the location you specified, which can be shared with your IT support team or Microsoft support for troubleshooting

Add-in Not Deploying via Microsoft Centralized Deployment

If the Opensense Outlook Add-in is not appearing for users after being assigned via Microsoft Centralized Deployment, follow these steps to resolve the issue.

1. Verify Deployment Status in Microsoft 365 Admin Center

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

  2. Find the Opensense Outlook Add-in and check the deployment status.

  3. Ensure that users are assigned to a supported group and that the deployment is marked as Active.

2. Confirm Group Assignments

Note: Microsoft does not support nested groups for add-in deployment.

  • Ensure that users are directly assigned to a top-level group (not a sub-group).

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

Solution

  • If the user is in a nested group, manually add them to a top-level Microsoft 365 group and reattempt deployment.

Supported Microsoft Documentation

3. Check Outlook Web Access (OWA) First

  • Sometimes, the add-in appears in OWA first before syncing to the Outlook desktop app.

  • Have the user log in to OWA and check if the add-in appears.

  • If the add-in appears in OWA but not in the desktop app, proceed to clear the add-in cache (see Step 5).

  • If the add-in does NOT appear in OWA, it indicates that the Outlook add-in did not propagate the necessary permissions to the user's profile (see Step 4).

4. Regrant Admin Consent (Fix Stuck Deployments)

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

Solution

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

  2. Wait 30-60 minutes to allow Microsoft 365 to process the removal.

  3. Re-add the user to the scope.

  4. Regrant admin consent:

    • Go to Azure AD Admin Center → Enterprise Applications.

    • Find Opensense Outlook Add-in.

    • Click Permissions (under Security) → Grant Admin Consent for the organization.

5. Clear Microsoft Add-in Cache

If the add-in is still missing, clearing the local add-in cache may force it to reappear.

Windows

  1. Close Outlook.

  2. Open File Explorer and go to:

%LOCALAPPDATA%\Microsoft\Office\16.0\Wef

  1. Delete the contents of the Wef folder.

  2. 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.

6. Manually Install the Add-in Using the Manifest File

Note: This is not available for GCC High deployments.

If the centralized deployment is failing, manually installing the add-in ensures users can access it.

Steps to Install Manually

  1. Download the Manifest File:

  2. Install the Add-in in Outlook:

7. Wait for M365 Sync & Check for Delays

  • Microsoft 365 can take up to 24-72 hours to sync add-in assignments.

  • If the add-in does not appear immediately after following the above steps, wait a few hours and retry launching Outlook.

8. Contact Opensense Support if Issues Persist

If the add-in still does not deploy after 72 hours and all steps have been followed:

  • Submit a ticket with Microsoft describing the issue in detail.

  • Email help@opensense.com to open a ticket.

  • Please provide the following details in your report:

    • Microsoft Support Ticket #:

    • Impacted User Emails:

    • Company/domain:

    • Date Started:

    • Outlook Client:

    • Outlook Version:

    • Issue:

Opensense Support

For further assistance, contact Opensense Support:

  • Email: help@opensense.com

  • Knowledge Base: help.opensense.com