Outlook Addin Web Based Icons Not Showing Up on Desktop

Question

Outlook Addin Web Based Icons Not Showing Up on Desktop

Pope, Mike 0

I'm doing developing for a web based outlook addin, using a manifest.xml file and the assets are deployed to an azure web service. When I visit the outlook addin from the browser, it shows up just fine, when trying to visit it on the Outlook Desktop app, the icons don't show up and it's blank

Has anyone experienced this? I've tried updating the panifest.xml file with query params, changing file names of icons, deleting 16.0 -> WEF file, nothing seems to work.

Outlook on web:
User's image

Outlook Desktop:

User's image

Polat Tunç 0 Reputation points

2026-03-16T14:09:44.2166667+00:00
Hi, any updates on this thread / has anyone managed to get the command icon to render in Outlook for Windows?

I’m seeing a very specific issue:

The add-in works (taskpane opens, commands execute, auth works) across clients.

In Outlook for Windows, the ribbon buttons show up and work, but the button icons are blank (this is only about the icon rendering).

What I’ve already tried/verified:

Command icons are defined in VersionOverrides and referenced via resid with the required sizes:

16x16, 32x32, 80x80

All icon URLs are HTTPS and return 200 OK with Content-Type: image/png.

Verified with curl that the icon responses contain no caching directives:

no Cache-Control, no Pragma, no Expires (only ETag / Last-Modified).

Tried forcing fresh downloads by changing icon filenames/URLs (v1 → v2), incrementing the manifest version, clearing the Office cache, and restarting Outlook for Windows.

The add-in uses displayReplyFormAsync, therefore Mailbox 1.9 is required.
Vy Nguyen 10,130 Reputation points Microsoft External Staff Moderator

2026-03-16T21:49:47.1266667+00:00
Hi @Polat Tunç,

Thank you for sharing such a detailed set of validation steps. Based on what you described, the add in is loading and executing correctly in Outlook for Windows, and the remaining gap is limited to how the desktop client is rendering the command icons on the ribbon.

In Classic Outlook for Windows, command icons are loaded from the PNG resources defined in VersionOverrides, and when the desktop client cannot successfully retrieve or accept an image exactly as expected, the command can still appear and work while the icon area remains blank.

To help narrow this down further, the most effective next checks are the following.

1/ Validate the icon assets and hosting one more time

Please confirm the three icons are truly PNG files at exactly 16x16, 32x32, and 80x80, are reachable over HTTPS, do not redirect, and do not require any authentication or conditional access.

Also double check the server is not returning any cache directives for these images, because that can cause Outlook to substitute a placeholder or show no icon.

2/ Force a full refresh of the Office add-in cache on Windows

Close Outlook and any other Office apps, then delete the contents of %LOCALAPPDATA%\Microsoft\Office\16.0\Wef.

If the add-in uses the unified manifest for Microsoft 365, also delete %userprofile%\AppData\Local\Microsoft\Outlook\HubAppFileCache.

After that, reopen Outlook and re-test the ribbon icons

3/ Contact IT administrator:

Since your account is managed by your organization, please contact your IT administrator to review your permissions and policies. If the issue persists after these checks, ask your IT administrator to submit a support request directly to Microsoft Support team.

They can raise a support ticket by visiting: Get support - Microsoft 365 admin | Microsoft Learn

As community moderators, we appreciate your understanding that our access to internal development details is limited. Our primary role is to guide users toward the appropriate resources and support channels. While we may not have visibility into deeper backend analysis, we’ll continue doing our best to support you within the scope of our responsibilities.

I hope this information is helpful. Please follow these steps and let me know if it works for you. If you have any updates regarding the issue, please feel free to share them with me.

Thank you so much for your patience and understanding throughout this process. Greatly Appreciate again for your patience and understanding.

2 answers

Your answer

Polat Tunç 0 Reputation points

2026-03-16T14:09:44.2166667+00:00

Hi, any updates on this thread / has anyone managed to get the command icon to render in Outlook for Windows?

I’m seeing a very specific issue:

The add-in works (taskpane opens, commands execute, auth works) across clients.

In Outlook for Windows, the ribbon buttons show up and work, but the button icons are blank (this is only about the icon rendering).

What I’ve already tried/verified:

Command icons are defined in VersionOverrides and referenced via resid with the required sizes:

16x16, 32x32, 80x80

All icon URLs are HTTPS and return 200 OK with Content-Type: image/png.

Verified with curl that the icon responses contain no caching directives:

no Cache-Control, no Pragma, no Expires (only ETag / Last-Modified).

Tried forcing fresh downloads by changing icon filenames/URLs (v1 → v2), incrementing the manifest version, clearing the Office cache, and restarting Outlook for Windows.

The add-in uses displayReplyFormAsync, therefore Mailbox 1.9 is required.

Answer 1

Vy Nguyen 10,130 Microsoft External Staff Moderator

Hi @Pope Mike,

Thank you for reaching out to the Microsoft Q&A forum and for clearly outlining your concern.

Based on the details you shared that your web‑based Outlook add‑in displays correctly in Outlook on the web while the ribbon buttons in Classic Outlook for Windows appear with blank icons. I truly understand and appreciate your effort updating the manifest, renaming icon files, and clearing the Office cache to narrow this down.

In Classic Outlook for Windows, the ribbon loads command icons strictly from the icon resources declared in the manifest and it expects three PNG images at specific sizes that are served over HTTPS. When the desktop client cannot retrieve a valid image or encounters an unsupported format, it substitutes a generic placeholder or shows a blank tile even though the button is present. Additionally, Outlook caches icon assets, so updated images do not appear until the Office cache is cleared or the icon URLs change.

Below are some workable options that might be the most appropriate for your current situation:

1/ Validate the icon assets and hosting

Confirm that the icons are PNG files sized exactly 16 by 16 pixels, 32 by 32 pixels, and 80 by 80 pixels, and that they are reachable over HTTPS. Avoid SVG because it is not a supported icon format for add‑in commands in Classic Outlook for Windows.
Open each icon URL in a private browser session and verify it returns an HTTP 200 response with the expected image content, and does not redirect to another location or require authentication.
Ensure the server does not include cache control response headers for these images because Office will replace your icon with a default image when such directives are present. If you recently changed an icon, use a new URL to force clients to download the new asset.
References:
- Image element in the manifest file - Office Add-ins | Microsoft Learn
- Icon guidelines for Office Add-ins - Office Add-ins | Microsoft Learn

2/ Review the manifest references for add‑in commands

In the Version Overrides section, verify that each button references the icon resource set and that the resource list includes the three required image sizes mentioned above.
Make sure all resource and command entries use absolute HTTPS links and that your manifest conforms to the current add‑in manifest guidance for Outlook. Increment the manifest version before redeploying so that clients pick up the changes.
Reference: Create add-in commands with the add-in only manifest - Office Add-ins | Microsoft Learn

3/ Refresh the desktop client cache to pull fresh assets

Fully close Outlook, then clear the Office cache on Windows and restart Outlook to force a fresh download of the manifest and image resources. This step is recommended whenever you change icon file names or URLs.
Reference: Clear the Office cache - Office Add-ins | Microsoft Learn

If the icons are still blank after these steps, I am ready to investigate further. Please share one example icon URL, the Outlook build number from About Outlook, and the icon resource entries from your manifest so I can analyze the behavior end‑to‑end.

I hope this response has helped address your question and clarify the behavior you're experiencing. Please feel free to reply if you have any further questions, I would be happy to assist further.

Thank you for your patience and your understanding. I look forward to continuing the conversation.

If the answer is helpful, please click "Accept Answer" and kindly upvote it. If you have extra questions about this answer, please click "Comment”.

Note: Please follow the steps in our documentation to enable e-mail notifications if you want to receive the related email notification for this thread.

Vy Nguyen 10,130 Reputation points Microsoft External Staff Moderator

2026-03-11T14:55:32.03+00:00

Hi @Pope Mike,

I hope everything is going well on your end.

I’m following up on the support thread we've been working through together. I wanted to check in and see if the information I shared in my previous answer helped resolve the issue you were experiencing.

If you're still experiencing any issues or have further questions, please feel free to reach out at any time. I’m always happy to help if you need anything else.

I want to ensure everything is functioning smoothly and that your experience remains seamless.

Thank you again for your collaboration throughout the troubleshooting process.

I look forward to hearing from you soon.

Polat Tunç 0

Below is my anonymised manifest excerpt (all URLs and IDs replaced):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OfficeApp
  xmlns="http://schemas.microsoft.com/office/appforoffice/1.1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0"
  xsi:type="MailApp">
  <Id><client-id></Id>
  <Version>1.0.0.5</Version>
  <ProviderName><provider></ProviderName>
  <DefaultLocale>de-DE</DefaultLocale>
  <DisplayName DefaultValue="<add-in-name>" />
  <Description DefaultValue="<description>" />
  <IconUrl DefaultValue="https://<myurl>/assets/icon-64-v2.png" />
  <HighResolutionIconUrl DefaultValue="https://<myurl>/assets/icon-128-v2.png" />
  <SupportUrl DefaultValue="https://<myurl>/" />
  <AppDomains>
    <AppDomain>https://<myurl></AppDomain>
  </AppDomains>
  <Hosts>
    <Host Name="Mailbox" />
  </Hosts>
  <Requirements>
    <Sets>
      <Set Name="Mailbox" MinVersion="1.1" />
    </Sets>
  </Requirements>
  <FormSettings>
    <Form xsi:type="ItemRead">
      <DesktopSettings>
        <SourceLocation DefaultValue="https://<myurl>/taskpane.html" />
        <RequestedHeight>450</RequestedHeight>
      </DesktopSettings>
    </Form>
    <Form xsi:type="ItemEdit">
      <DesktopSettings>
        <SourceLocation DefaultValue="https://<myurl>/taskpane.html" />
      </DesktopSettings>
    </Form>
  </FormSettings>
  <Permissions>ReadWriteItem</Permissions>
  <Rule xsi:type="RuleCollection" Mode="Or">
    <Rule xsi:type="ItemIs" ItemType="Message" FormType="Read" />
    <Rule xsi:type="ItemIs" ItemType="Message" FormType="Edit" />
  </Rule>
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
    <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
      <Requirements>
        <bt:Sets DefaultMinVersion="1.9">
          <bt:Set Name="Mailbox" />
        </bt:Sets>
      </Requirements>
      <Hosts>
        <Host xsi:type="MailHost">
          <DesktopFormFactor>
            <ExtensionPoint xsi:type="MessageReadCommandSurface">
              <OfficeTab id="TabDefault">
                <Group id="msgReadGroup">
                  <Label resid="GroupLabel" />
                  <Control xsi:type="Button" id="msgReadOpenPaneButton">
                    <Label resid="TaskpaneButton.Label" />
                    <Supertip>
                      <Title resid="TaskpaneButton.Label" />
                      <Description resid="TaskpaneButton.Tooltip" />
                    </Supertip>
                    <Icon>
                      <bt:Image size="16" resid="Icon.16x16" />
                      <bt:Image size="32" resid="Icon.32x32" />
                      <bt:Image size="80" resid="Icon.80x80" />
                    </Icon>
                    <Action xsi:type="ShowTaskpane">
                      <SourceLocation resid="Taskpane.Url" />
                    </Action>
                  </Control>
                </Group>
              </OfficeTab>
            </ExtensionPoint>
            <ExtensionPoint xsi:type="MessageComposeCommandSurface">
              <OfficeTab id="TabDefault">
                <Group id="msgComposeGroup">
                  <Label resid="GroupLabel" />
                  <Control xsi:type="Button" id="msgComposeOpenPaneButton">
                    <Label resid="TaskpaneButton.Label" />
                    <Supertip>
                      <Title resid="TaskpaneButton.Label" />
                      <Description resid="TaskpaneButton.Tooltip" />
                    </Supertip>
                    <Icon>
                      <bt:Image size="16" resid="Icon.16x16" />
                      <bt:Image size="32" resid="Icon.32x32" />
                      <bt:Image size="80" resid="Icon.80x80" />
                    </Icon>
                    <Action xsi:type="ShowTaskpane">
                      <SourceLocation resid="Taskpane.Url" />
                    </Action>
                  </Control>
                </Group>
              </OfficeTab>
            </ExtensionPoint>
          </DesktopFormFactor>
        </Host>
      </Hosts>
      <Resources>
        <bt:Images>
          <bt:Image id="Icon.16x16" DefaultValue="https://<myurl>/assets/icon-16-v2.png" />
          <bt:Image id="Icon.32x32" DefaultValue="https://<myurl>/assets/icon-32-v2.png" />
          <bt:Image id="Icon.80x80" DefaultValue="https://<myurl>/assets/icon-80-v2.png" />
        </bt:Images>
        <bt:Urls>
          <bt:Url id="Taskpane.Url" DefaultValue="https://<myurl>/taskpane.html" />
        </bt:Urls>
        <bt:ShortStrings>
          <bt:String id="GroupLabel" DefaultValue="<group-label>" />
          <bt:String id="TaskpaneButton.Label" DefaultValue="<button-label>" />
        </bt:ShortStrings>
        <bt:LongStrings>
          <bt:String id="TaskpaneButton.Tooltip" DefaultValue="<tooltip>" />
        </bt:LongStrings>
      </Resources>
      <WebApplicationInfo>
        <Id><client-id></Id>
        <Resource>api://<myurl>/<client-id></Resource>
        <Scopes>
          <Scope>User.Read</Scope>
          <Scope>email</Scope>
          <Scope>openid</Scope>
          <Scope>profile</Scope>
        </Scopes>
      </WebApplicationInfo>
    </VersionOverrides>
  </VersionOverrides>
</OfficeApp>

Polat Tunç 0 Reputation points

2026-03-16T14:12:54.21+00:00
Hi, any updates on this thread / has anyone managed to get the command icon to render in Outlook for Windows?

I’m seeing a very specific issue:

The add-in works (taskpane opens, commands execute, auth works) across clients.

In Outlook for Windows, the ribbon buttons show up and work, but the button icons are blank (this is only about the icon rendering).

What I’ve already tried/verified:

Command icons are defined in VersionOverrides and referenced via resid with the required sizes:

16x16, 32x32, 80x80

All icon URLs are HTTPS and return 200 OK with Content-Type: image/png.

Verified with curl that the icon responses contain no caching directives:

no Cache-Control, no Pragma, no Expires (only ETag / Last-Modified).

Tried forcing fresh downloads by changing icon filenames/URLs (v1 → v2 → v3), incrementing the manifest version, clearing the Office cache, and restarting Outlook for Windows.

The add-in uses displayReplyFormAsync, therefore Mailbox 1.9 is required.Hi, any updates on this thread / has anyone managed to get the command icon to render in Outlook for Windows? I’m seeing a very specific issue:

The add-in works (taskpane opens, commands execute, auth works) across clients.

In Outlook for Windows, the ribbon buttons show up and work, but the button icons are blank (this is only about the icon rendering).

What I’ve already tried/verified:

Command icons are defined in VersionOverrides and referenced via resid with the required sizes:

16x16, 32x32, 80x80

All icon URLs are HTTPS and return 200 OK with Content-Type: image/png.

Verified with curl that the icon responses contain no caching directives:

no Cache-Control, no Pragma, no Expires (only ETag / Last-Modified).

Tried forcing fresh downloads by changing icon filenames/URLs (v1 → v2 → v3), incrementing the manifest version, clearing the Office cache, and restarting Outlook for Windows.

The add-in uses displayReplyFormAsync, therefore Mailbox 1.9 is required.

Above is my manifest.

Questions:

Are there known issues in Outlook for Windows where command icons render blank depending on PNG encoding (interlacing, bit depth, color profile, alpha channel), even when the file is a valid PNG and served correctly?

Is it recommended to try BMP for command icons as a workaround for Outlook for Windows?

Is there a way to get diagnostic logging for icon retrieval/decoding in Outlook for Windows (to confirm whether it fetches the icon URLs and whether decoding fails)?

Thanks for any guidance.
Pope, Mike 0 Reputation points

2026-03-26T18:47:05.6366667+00:00

Thanks for the response! So here I am accessing the image asset png file through the browser and it renders no problem, this is for asset at url:

Url - https://app-kwery-office-addin-dev-001.azurewebsites.net/assets/icon-16-kwery.png
Pope, Mike 0 Reputation points

2026-03-26T18:56:44.7833333+00:00

In the network request for the png, it also responses with the pragma no cache header, here is a screenshot of the returning network request.
Vy Nguyen 10,130 Reputation points Microsoft External Staff Moderator

2026-03-26T18:57:19.92+00:00

As this forum is a public platform, we’ve taken steps to help protect your privacy by removing your organization’s domain name from your message. To ensure your data remains secure, we kindly recommend avoiding the inclusion of personal or organizational details such as domain names or screenshots with sensitive information in future posts.

Hi @Pope Mike,

Thank you for getting back to me and for confirming this. I really appreciate you taking the time to check the PNG asset in the browser and sharing the URL.

If you have any concerns or questions in the future, please don’t hesitate to reach out. Not only will I be happy to assist you, but all moderators in the Q&A forum will also do their best to provide support and guidance.

I truly appreciate your time and cooperation throughout the resolution of this matter.

Thank you for being a valued customer and for contacting us on the Microsoft Q&A forum.
Pope, Mike 0 Reputation points

2026-03-26T19:00:53.8666667+00:00

Here is an image of what all of our resource images are defined as inside of the manifest.xml file

Answer 2

On classic Outlook for Windows, the most common causes for web add-in icons not appearing (blank button, missing icon) are a stale/corrupted cached manifest or an icon definition that doesn’t meet the desktop client’s requirements.

Use the following checks and fixes:

Verify Outlook has a valid cached manifest
1. Close Outlook.
2. Confirm the add-in is correctly installed and enabled for the mailbox in Exchange Admin Center.
3. On the desktop where Outlook is running, check the cache folder:
```
      %LocalAppData%\Microsoft\Office\16.0\WEF
```
4. Locate the subfolder for the add-in:
```
      <guid>\<base64 hash>\Manifests\<ManifestID>_<ManifestVersion>
```
  Ensure the manifest for the add-in is present.
5. If the manifest was modified while Outlook was open, uninstall the add-in from Exchange Admin Center, reinstall it, then restart Outlook and test again.
Clear Office cache when changing manifest or icons
- When changing icon file names, URLs, or other manifest elements, clear the Office cache so Outlook picks up the latest manifest and assets. Follow the steps in “Clear the Office cache” referenced from the troubleshooting article, then restart Outlook and test.
Validate manifest and icon definitions
- Run the manifest through the validation guidance in “Validate an Office Add-in’s manifest” and use runtime logging if needed.
- For the IconUrl (and HighResolutionIconUrl) elements:
  - Ensure the image format is one of: BMP, EXIF, GIF, JPG, PNG, or TIFF.
  - Ensure the resolution matches the add-in type. For a mail add-in, the icon must be 64x64 pixels.
  - The URL must be reachable from the desktop client (no auth prompts, correct HTTPS endpoint, no 404/403).
- Remember that changing IconUrl at runtime is not supported; changes must be made in the manifest and then re-deployed/recached.
Turn on UI error reporting in Outlook
1. Remove/sideload the add-in again.
2. In Outlook, go to File > Options > Advanced.
3. In the Developers section, enable Show add-in user interface errors.
4. Sideload or re-add the add-in and watch for any UI-related error messages that might explain why icons are not rendering.
If seeing “This add-in is no longer available”
- Ensure the manifest’s ID has not been changed in the deployed copy without first removing the old add-in.
- Check that all resid values used in the manifest are defined in the <Resources> section, spelled exactly the same, and are 32 characters or fewer.
- Clear the Office cache if the ID or resources were changed.

If the add-in loads in Outlook on the web but desktop icons remain blank after these steps, focus on:

Confirming the icon URLs are accessible from the desktop environment (firewall/proxy/CDN issues).
Verifying the icon size and format exactly match the requirements for mail add-ins.
Ensuring Outlook is using the latest manifest by reinstalling the add-in and clearing the cache.

References:

Share via

Outlook Addin Web Based Icons Not Showing Up on Desktop

2 answers

Your answer