Troubleshooting the Outlook Add-in

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

For issues specific to GCC High environments, see Opensense Outlook Add-in integration with GCC High environments.

Symptoms

Use this guide if you’re experiencing any of these:

• The add-in doesn’t appear at all, or appears in some Outlook clients but not others. See Add-in not appearing or not working.
• 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. See Field edits not populating data.
• The signature doesn’t appear while using Quick Reply on Outlook Mobile. See Quick Reply on Outlook Mobile.

Clear the add-in cache first

Clearing the add-in cache resolves most inconsistent behavior (wrong signature, stale fields, auto-insert failures). Open the Opensense add-in pane, go to Settings, find Cache, and then select Clear. The current add-in version shows at the bottom of the pane on every screen. Try this first for any behavior that seems off.

Before you begin

Confirm that the affected user meets all the environment and license requirements before you work through the steps below. For the full list of supported Outlook versions, license requirements, and unsupported environments, see Outlook Add-in supported environments.

Also confirm that:

• 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) load and run add-ins differently. This matters when troubleshooting: a problem may appear in one client but not the other, and the cause is different in each case.

Client	Runtime	Add-in loaded through
Classic Outlook (desktop)	Desktop app; add-ins run in Microsoft Edge WebView2	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 that the add-in works in New Outlook or OWA but not in Classic Outlook, start by clearing the Outlook cache folders, as described in Step 3.

Classic Outlook and the EWS retirement

Microsoft is retiring EWS in Exchange Online. Since October 1, 2026, Microsoft has been turning off EWS for organizations that haven’t set up EWS access, and EWS will be off for every organization in April 2027. When EWS is off, web add-ins, including Opensense, may not work in Classic Outlook on Microsoft 365 Apps for Windows builds earlier than 16.0.19725. If the add-in works in New Outlook and OWA but not in Classic Outlook, ask your IT administrator whether EWS is turned off for your organization, and update Microsoft 365 Apps to build 16.0.19725 or later. See Microsoft’s Exchange Web Services requirements.

Solution: Add-in not appearing or not working

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

Step 1: Check Outlook on the Web (OWA)

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

Appears in OWA, but not in the Outlook desktop app

The deployment has reached the user, so the issue is client-side. Continue to Step 2.

Doesn't appear in OWA

The deployment hasn't propagated to the user's profile. Skip to Step 4.

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 turned off, it may stop the add-in from loading, even when it’s deployed correctly. Confirm this quick setting before you move on to clearing caches.

1. Open the Outlook desktop app.
2. Select File, and then select Office Account.
3. Under Account Privacy, select Manage Settings.
4. Check the box for Turn on optional connected experiences.
5. Select OK to save, and then restart Outlook.

You can also reach the same settings from File > Options > Trust Center > Trust Center Settings > Privacy Options > Privacy Settings. In New Outlook, go to View > View settings > General > Privacy and data, and then select Privacy settings.

Your organization’s Group Policy or Microsoft 365 Apps admin policy may control this setting. If the checkbox is greyed out, contact your IT administrator to turn on Optional connected experiences at the tenant level.

Add-in back?

If the add-in appears after you restart, turning on Optional connected experiences resolved the issue. No further steps are 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. On Windows, complete both parts before you restart Outlook.

Windows

Part 1, the HubAppFileCache folder:

1. Close Outlook completely, and confirm that it isn’t 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 add _old to the end of the name (for example, HubAppFileCache_old).

Part 2, the 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.

When both folders are renamed, restart Outlook, and check whether the add-in appears.

Mac

1. Quit Outlook completely.

2. Open Terminal, and run this 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.

What to do next

If the add-in appears after you restart, a stale cache was the cause, and no further steps are needed. If the add-in loads but produces no signature, skip to Step 5. If the add-in still doesn’t appear at all, continue to Step 4.

Step 4: Verify deployment in Microsoft 365 Admin Center

Do this step if the add-in didn’t appear in OWA in Step 1, or if more than 72 hours have passed since deployment and the add-in still hasn’t appeared. An IT administrator needs to complete it.

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

1. In the Microsoft 365 admin center, go to Settings > Integrated apps.
2. Find the Opensense Outlook Add-in, and confirm that its deployment status is Active.
3. Confirm that the affected users are 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 the earlier steps haven’t resolved the problem. Select the symptom that matches.

Error or blank signature when switching the From address

Likely cause: the sending domain isn't in the Opensense Internal Domains list.

Add the domain to the list. For the full steps, see Configuring Internal Domains. Clearing the cache won't resolve a 400 Unauthorized error with a present Azure Token.

Add-in pane is blank, with no error

Likely cause: no signature is routed to the user.

1. Go to Signatures > Routing, and confirm that a route covers the user.
2. Use User Signature Lookup in the Resources drop-down to confirm that the user is mapped to a template.
3. If there's 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 doesn't appear in Opensense

Likely cause: directory sync hasn't run yet for a newly created user.

1. Go to Manage > Domains, select the ellipsis (...) on the domain card, and then select Manage Domain.
2. Go to Manage > Users.
3. If the user is missing, go to Actions > Run Sync, select the directory source and users, and then select Start Sync.

If the user still doesn't appear after the sync, contact help@opensense.com.

Step 6: Confirm user assignment method and scope

Microsoft Centralized Deployment supports three assignment methods. Each behaves differently, with its own considerations.

Assignment method	Behavior	Considerations
Entire organization	Applies to all users in the tenant	Use only if all outbound email should get an Opensense signature
Group	Applies to members of the assigned group; membership changes apply automatically	Microsoft's recommended approach. Top-level groups only (no nested groups).
Individual users	Applies to explicitly assigned users only; new users must be added manually	Users are more often missed during onboarding, and there are no automatic updates when users join or leave

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

If a user was assigned the add-in but it never appeared, or if they were recently re-added to the scope, their profile may be stuck. Removing and re-adding the user resets the deployment queue for that account, without affecting anyone else. For how to remove and re-add a user in the group, see Scoping Outlook Add-in users in the Microsoft 365 admin center.

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. In the Microsoft Entra admin center, go to Entra ID > Enterprise apps > All applications, and find Opensense Email Signatures. Under Security, select Permissions, and then select Grant admin consent for your organization. (This was formerly the Azure AD admin center, under Enterprise Applications.) For full steps, see Step 3 of the scoping article.

Re-grant after every scope change

Re-grant admin consent 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 change.

Step 8: Verify org-level add-in enablement

If no add-ins appear for any users in the tenant, the org-level add-in setting may be turned off. Ask your Exchange administrator to run this in Exchange Online PowerShell:

Get-OrganizationConfig | fl AppsForOfficeEnabled

If it returns False, run this to turn add-ins back on:

Set-OrganizationConfig -AppsForOfficeEnabled:$True

Don’t set this to False

Setting AppsForOfficeEnabled to False turns off all add-ins for all users across the organization, overriding all admin and user role settings. Don’t set it to False in a tenant where add-ins are expected to work.

Solution: Field edits not populating data

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

1. Check whether field editing is restricted for this user. Fields controlled by the Opensense admin show a lock icon, and can’t be edited, whatever the user enters. If all fields are locked, contact your Opensense admin.
2. If fields are editable but values aren’t saving, avoid clicking quickly through the Settings tab while it loads. This can put the add-in in 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. Go back to the Signatures tab, let the add-in fully load, and then return to the Settings tab. If values are still blank after a full load, go to Settings > Cache > Clear to force a fresh sync from the Opensense backend.

Blank values overwrite data

Saving blank field values overwrites any existing data for that user. Always confirm that the add-in has fully loaded before you make edits.

How to verify the fix

Field values populate correctly in the Settings tab, and persist after you close and reopen the add-in pane.

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

When you reply with Quick Reply in Outlook Mobile, the signature doesn’t appear while you type. This is expected behavior, not a bug. The signature is applied automatically when the message is sent: you briefly see it insert as the message goes out, and the recipient receives it normally.

Signature in the Sent folder?

If a user reports a missing signature specifically when using Quick Reply, but the signature is 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 hasn’t appeared after 72 hours, and you’ve completed all the steps above, contact both Microsoft and Opensense support.

Contacting Microsoft support

• Ask for engineering to review the tenant-level logs for the affected user accounts.
• Include the affected users’ email addresses, and the date the issue started.

Contacting Opensense support

Email help@opensense.com, and include:

• The Microsoft support ticket number (if you have one)
• The affected users’ email addresses
• Company name and domain
• The date the issue started
• The Outlook client and version (Classic Outlook, New Outlook, OWA, Mac, Mobile)
• Which clients the add-in works in, and which it doesn’t
• The assignment method used (individual users, group, entire organization)
• A description of the issue, and the steps already tried

What’s next

• Outlook Add-in overview: deployment methods and the Outlook Mobile account-switching limitation
• Scoping Outlook Add-in users in the Microsoft 365 admin center
• Configuring the Outlook Add-in in Domain Settings: SVG image limitations and Internal Domains
• Expected behaviors in routed Outlook Add-in deployments
• Setting up multiple signatures in the Outlook Add-in: mobile signature selection and Allow Default Override behavior
• Allowing Opensense traffic through your network proxy or firewall