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.

For issues specific to GCC High environments, see Opensense Add-in Integration with GCC High Environments.

Before troubleshooting
Most inconsistent behavior (wrong signature, stale fields, auto-insert failures) is resolved by clearing the add-in cache. Open the Opensense add-in pane, go to Settings, and select Clear Cache. This should be your first move for any behavior that seems off.

Before you begin

Confirm the affected user meets all environment and license requirements before working through the steps below. See Supported Environments Outlook Add-in for the full list of supported Outlook versions, license requirements, and unsupported environments.

Key things to confirm before troubleshooting

The user has an active Exchange Online mailbox. Newly created accounts may take several hours to fully provision.
The user is signed in with organizational credentials, not a personal Microsoft account.

Understanding Classic Outlook vs. New Outlook and OWA

Classic Outlook (the traditional desktop application) and New Outlook or Outlook on the Web (OWA) use different underlying runtimes to load and run add-ins. This distinction matters when troubleshooting because a problem may appear in one client but not the other, and the cause is different in each case.

Client	Runtime	Add-in loaded via
Classic Outlook (desktop)	COM-based desktop runtime	Exchange Web Services (EWS)
New Outlook (desktop)	Browser-based (Chromium)	Microsoft REST / Graph API
Outlook on the Web (OWA)	Browser-based	Microsoft REST / Graph API

If a user reports the add-in working in New Outlook or OWA but not in Classic Outlook, start by clearing the Outlook cache folders as described in Step 3.

Known limitations

Mobile signature behavior

The Opensense Outlook Add-in supports iOS and Android via an updated manifest. On mobile, the signature inserts automatically while composing new emails and reply-all replies. This is expected behavior and matches desktop behavior for those compose types.

Quick Reply on Outlook mobile

When replying via Quick Reply in Outlook mobile, the signature does not appear while you are typing. This is expected. The signature is applied automatically on send — you will briefly see it insert as the message goes out. The recipient receives the signature as normal.

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. The signature will always reflect the primary account on mobile regardless of which From address is selected.

Multi-signature selection on mobile

Multi-signature selection is available on mobile if the user's Opensense configuration includes the option to save their signature selection. When that setting is enabled, the selection made in the add-in pane persists when the user goes to compose. If the save option is not enabled, any selection made in the add-in pane will revert to the default when the compose window opens. If a user reports their signature selection not sticking on mobile, confirm whether the save selection setting is enabled in their Opensense configuration.

SVG images in signature templates

SVG images in a signature template will cause the visual preview insert to fail entirely when the add-in is used — not just render incorrectly. All images in add-in-deployed signatures must use PNG or JPG format. This applies to logos, headshots, and any other image elements in the template. If a user reports the signature not inserting and the template contains SVG images, replacing them with PNG or JPG will resolve it.

For a full list of supported clients and platform-specific behavior, see Supported Environments Outlook Add-in.

Inconsistent add-in behavior

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

Field edits not populating data

Check whether field editing is restricted for this user. Fields controlled by the Opensense admin will display a lock icon and cannot be edited regardless of what the user enters. If all fields are locked, contact your Opensense admin.
If fields are editable but values are not saving, avoid clicking rapidly through the Settings tab while it is loading. This can cause the add-in to enter a partial load state before user data has fully synced from the backend.
If all field values are blank, do not attempt to update them yet. Navigate back to theSignaturestab, allow the add-in to fully load, then return to theSettingstab. If values remain blank after a full load, go toSettings > Cache > Clearto force a fresh sync from the Opensense backend.

Saving blank field values will overwrite any existing data for that user. Always confirm the add-in has fully loaded before making edits.

Add-in not appearing or not working

Work through the steps below in order. Stop when the issue is resolved. Step 1 tells you where to start based on what you are seeing.

Step 1: Check Outlook on the Web (OWA)

OWA is the fastest way to determine whether the issue is a deployment problem or a client-side problem. Check OWA before doing anything else.

If the add-in appears in OWA but not in the Outlook desktop app, the deployment has reached the user. The issue is client-side. Continue to Step 2.
If the add-in does not appear in OWA, the deployment has not propagated to the user's profile. Skip to Step 4.
If the add-in appears in OWA and New Outlook but not in Classic Outlook, the issue is specific to the Classic Outlook client. Continue to Step 2.

Step 2: Check Optional Connected Experiences

If Optional Connected Experiences is disabled, it may prevent the add-in from loading even when correctly deployed. This is a quick setting to confirm before moving to cache clears.

Open the Outlook desktop app.
Select File from the ribbon, then select Options.
Select Trust Center, then select Trust Center Settings.
Select Privacy Options, then select Privacy Settings.
Check the box for Turn on optional connected experiences.
Select OK to save, then restart Outlook.

This setting may be controlled by your organization's Group Policy or Microsoft 365 Apps admin policy. If the checkbox is greyed out, contact your IT administrator to enable Optional Connected Experiences at the tenant level.

If the add-in appears after restarting, enabling Optional Connected Experiences resolved the issue. No further steps needed.

Step 3: Clear the add-in cache folders

Clearing both cache folders resolves the vast majority of add-in disappearance and auto-insert failures. Complete both parts below before restarting Outlook.

Windows

Part 1: HubAppFileCache

Close Outlook completely and confirm it is not running in the background.
Open File Explorer (Windows key + E).
Click the address bar, paste %localappdata%\Microsoft\Outlook, and press Enter.
Right-click the HubAppFileCache folder, select Rename, and append _old to the name (for example: HubAppFileCache_old).

Part 2: Wef folder

In File Explorer, click the address bar, paste %localappdata%\Microsoft\Office\16.0, and press Enter.
Rename the Wef folder to Wef_old.

Once both folders have been renamed, restart Outlook and check whether the add-in appears.

Mac

Quit Outlook completely.
Open Terminal and run the following command to clear the Wef cache:

rm -rf ~/Library/Containers/com.microsoft.Outlook/Data/Library/Application\ Support/Microsoft/Office/16.0/Wef

Restart Outlook and check whether the add-in appears.

If the add-in appears after restarting, a stale cache was the cause. No further steps needed. If the add-in loads but produces no signature, skip to Step 5. If the add-in still does not appear at all, continue to Step 4.

Step 4: Verify deployment in Microsoft 365 Admin Center

If the add-in did not appear in OWA in Step 1, or if it has been more than 72 hours since deployment and the add-in still has not appeared, confirm the deployment status in the Microsoft 365 Admin Center.

A new add-in deployment can take up to 24 hours to appear for assigned users. Changes made after initial deployment, including turning the add-in on or off or modifying the user scope, can take up to 72 hours to propagate. Confirm how long it has been since the add-in was assigned or modified before proceeding.

Go to Microsoft 365 Admin Center > Settings > Integrated Apps.
Locate the Opensense Outlook Add-in and confirm the deployment status is Active.
Confirm the affected users are included in the deployment scope.

Step 5: Verify the Opensense configuration

This step applies when the add-in loads but produces no signature. These issues are less common than client-side or deployment issues but are worth checking if all prior steps have not resolved the problem.

Symptom	Likely cause	Resolution
Error or blank signature when switching From address	Sending domain not in Opensense Internal Domains list	See Outlook Add-in Domain Settings for the full configuration steps. A `400 Unauthorized` error with a present Azure Token will not be resolved by clearing the cache.
Add-in pane is blank with no error	No signature routed to the user	Go to Signatures > Routing and confirm a route covers the user. Use User Signature Lookup under the Resources dropdown to confirm they are mapped to a template. If no result, add the user to a group with a route, or update the All Users route to point to the correct HTML template.
User does not appear in Opensense	Directory sync has not yet run for a newly created user	Go to Manage > Domains, click the ellipses on the domain card, select Manage Domain, then go to Manage > Users. If the user is missing, go to Actions > Run Sync, select the directory source and users, and click Start Sync. If they still do not appear after syncing, contact help@opensense.com.

Step 6: Confirm user assignment method and scope

Microsoft Centralized Deployment supports three assignment methods. Each has different behavior and considerations.

Assignment method	Behavior	Considerations
Entire organization	Applies to all users in the tenant	Use only if all outbound email should receive an Opensense signature
Group	Applies to members of the assigned group; membership changes apply automatically	Microsoft's recommended approach; requires top-level groups only (no nested groups)
Individual users	Applies to explicitly assigned users only; new users must be added manually	More prone to users being missed when onboarding; no automatic updates when users join or leave

If a user was previously assigned the add-in but it never appeared, or if they were recently re-added to the scope, their profile may be in a stuck state. Removing and re-adding the user resets the deployment queue for that account.

Remove the user from the add-in's deployment scope in Integrated Apps.
Wait 30 to 60 minutes for Microsoft 365 to process the removal.
Re-add the user to the scope.
Go to Azure AD Admin Center > Enterprise Applications, find Opensense Email Signatures, and select Permissions > Grant Admin Consent for the organization.

Admin consent should be re-granted any time users or groups are added to or removed from the deployment scope. This is especially important after the initial deployment and after any scope changes.

Step 8: Verify org-level add-in enablement

If no add-ins are appearing for any users in the tenant, the org-level add-in setting may be disabled. Have your Exchange administrator run the following in Exchange Online PowerShell:

Get-OrganizationConfig | fl AppsForOfficeEnabled

If this returns False, run the following to re-enable it:

Set-OrganizationConfig -AppsForOfficeEnabled:$True

Setting AppsForOfficeEnabled to False disables all add-ins for all users across the organization, overriding all admin and user role settings. This should not be set to False in a tenant where add-ins are expected to function.

Still having issues?

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

When contacting Microsoft support:

Request that engineering review tenant-level logs for the affected user accounts
Include the affected user email addresses and the date the issue started

When contacting Opensense support, include the following:

Microsoft Support Ticket number (if applicable)
Affected user email addresses
Company name and domain
Date the issue started
Outlook client and version (Classic Outlook, New Outlook, OWA, Mac, Mobile)
Which clients the add-in works in vs. which it does not
Assignment method used (individual users, group, entire organization)
Description of the issue and steps already attempted

Email Opensense support: help@opensense.com

Documentation Index