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 below, ordered from most to least common.

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

Symptoms

Use this guide if you're experiencing any of the following:

• The add-in doesn't appear at all, or appears in some Outlook clients but not others

• The signature is missing, stale, or doesn't match your settings when composing

• Field values in the add-in pane aren't saving or are showing blank

• The signature doesn't appear while using Quick Reply on Outlook Mobile

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, select Cache, then select Clear. The current add-in version is displayed at the bottom of the pane on every screen. Try this first 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.

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 of the solution below.

Solution: Add-in not appearing or not working

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

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.

1. Open the Outlook desktop app.

2. Select File from the ribbon, then select Options.

3. Select Trust Center, then select Trust Center Settings.

4. Select Privacy Options, then select Privacy Settings.

5. Check the box for Turn on optional connected experiences.

6. 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: Rename 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

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

Part 2: Wef folder

1. In File Explorer, click the address bar, paste %localappdata%\Microsoft\Office\16.0, and press Enter.

2. Rename the Wef folder to Wef_old.

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

Mac

1. Quit Outlook completely.

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

3. 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. This will need to be completed by an IT administrator.

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.

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

Step 6: Confirm user assignment method and scope

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

Step 7: Re-grant admin consent and reset the user's scope

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.

To reset a single user without affecting anyone else, see Scope Users for Opensense Outlook Add-in via Microsoft 365 Admin for how to remove and re-add a user from the group.

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

2. Wait 30 to 60 minutes for Microsoft 365 to process 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.

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.

Solution: Field edits not populating data

If field values aren't saving, or fields appear blank, this is usually caused by a partial sync between the add-in and the Opensense backend, not a real data loss.

Steps to fix:

1. Check whether field editing is restricted for this user. Fields controlled by the Opensense admin display a lock icon and cannot be edited regardless of what the user enters. If all fields are locked, contact your Opensense admin.

2. If fields are editable but values aren't saving, avoid clicking rapidly through the Settings tab while it's loading. This can cause the add-in to enter a partial load state before user data has fully synced from the backend.

3. If all field values are blank, don't update them yet. Navigate back to the Signatures tab, allow the add-in to fully load, then return to the Settings tab. If values remain blank after a full load, go to Settings > Cache > Clear to force a fresh sync from the Opensense backend.

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

How to verify it's fixed: Field values populate correctly in the Settings tab and persist after closing and reopening the add-in pane.

Solution: Signature doesn't appear during Quick Reply on Outlook Mobile

When replying via Quick Reply in Outlook Mobile, the signature does not appear while typing. This is expected behavior, not a bug. The signature is applied automatically when the message is sent, you'll briefly see it insert as the message goes out, and the recipient receives it normally.

If a user reports a missing signature specifically when using Quick Reply, but confirms the signature is present in the Sent folder afterward, no further action is needed. This is a limitation of the Quick Reply interface itself, not the add-in.

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

Related articles

• Outlook Add-in Overview, deployment methods and the Outlook Mobile account-switching limitation

• Outlook Add-in: Scope Users via Microsoft 365 Admin

• Supported Environments for the Opensense Outlook Add-in

• Outlook Add-in Routed Key Behaviors

• Outlook Add-in Domain Settings with Scenarios and Best Practices, SVG image limitations and Internal Domains configuration

• Outlook Add-in Multi-Signature Selector, mobile signature selection and Allow Default Override behavior

• Opensense Add-in Integration with GCC High Environments

• Allowing Opensense Traffic Through Your Network Proxy or Firewall