/debug

description: Diagnose deployment issues (stale config, connect failures, missing add-in)

Debug a Claude Office deployment

You are helping an enterprise admin diagnose why the deployed add-in isn't working right. Start by asking **what's wrong**, then route.

Triage

Ask the admin to describe the symptom. Route by answer:

| Symptom | Section | |---|---| | Updated the manifest but users still see old config | [Stale config after update](#stale-config-after-update) | | Add-in shows "Connection failed" | [Read the error paste](#read-the-error-paste) | | Add-in doesn't appear in Excel/PowerPoint at all | [Add-in not visible](#add-in-not-visible) | | Want to test/iterate a manifest locally before deploying | [Sideload a manifest for local debugging](#sideload-a-manifest-for-local-debugging) | | Sign-in popup fails or loops | [Admin consent](#admin-consent) | | Need to see the browser console | [Opening browser devtools](#opening-browser-devtools-on-the-add-in) |

If they have an error paste from the add-in (the **Copy error details** button on the connect-failed screen), always start there. It carries everything.

---

Read the error paste

Paste structure:

Claude for Office connection failed (<Provider>)
Build: <sha>

<friendly message>

Request:
  <key>: <value actually sent>
  ...

Manifest params:
  <key>: <value the deployed manifest carries>
  ...

Raw error:
<SDK/HTTP error>

**What to check:**

• `Request:` vs `Manifest params:` delta. Keys are the same snake_case names

in both blocks, so diff directly. If they differ, the user typed override values into the form. If they match, the manifest values went through unchanged.

• `Manifest params:` `m` key is the version tag (e.g. `unified-1.0.0.11`). If

it's below what you last uploaded, the user is on a stale manifest. Go to [Stale config](#stale-config-after-update).

• `Raw error:` is the ground truth. Common patterns:
• `invalid_client` (401, Google) → wrong `google_client_secret` for that

`google_client_id`. Verify in GCP Console → Credentials.

• `Load failed (<host>)` → network blocked at the WebView layer. Firewall

needs to allow that host.

• `STS AssumeRoleWithWebIdentity failed` → AWS IAM OIDC provider

misconfigured or role trust policy wrong.

• `HTTP 401/403` (gateway) → bad token or gateway rejected the key.

---

Stale config after update

Two caches, two clocks:

| Layer | Who holds it | TTL | How to clear | |---|---|---|---| | Service | M365 Admin Center → Exchange Online → client | Up to **72h** for updates (24h for fresh deploys) | Wait, or redeploy with a fresh `<Id>` | | Client | Office app's Wef folder on each machine | Until app restart, sometimes longer | Clear the cached manifests (see below) |

Microsoft's own FAQ: > It can take up to 72 hours for add-in updates, changes from turn on or turn off to reflect for users. > https://learn.microsoft.com/en-us/microsoft-365/admin/manage/centralized-deployment-faq

Confirm what Admin Center is serving

Admin Center silently ignores re-uploads with the same `<Version>`. If you uploaded a fix without bumping the fourth segment, it never took. Open M365 Admin Center → Integrated apps → your add-in → check the listed version.

Force a client-side refresh

A stale **sideloaded** manifest is stored differently per platform:

• **macOS** — a file `<addin-id>.manifest-*.xml` in each app's

`Documents/wef` folder, alongside every other add-in.

• **Windows** — a **registry** value under

`HKCU:\SOFTWARE\Microsoft\Office\16.0\Wef\Developer` (there is no per-add-in file to delete; clearing the `Wef` *folder* is a different, blunter operation — see the caveat below).

Use the helper scripts. They target **only** your add-in's `<Id>` and do direct `rm`/registry edits — they do **not** shell out to `office-addin-dev-settings` (its removal path has burned us on customer calls):

• macOS: [`scripts/clear-addin-cache.sh`](../scripts/clear-addin-cache.sh)
• Windows: [`scripts/clear-addin-cache.ps1`](../scripts/clear-addin-cache.ps1)

Quit Excel/Word/PowerPoint first. The scripts are **ID-first** — pass the add-in `<Id>` directly (handy when iterating across new/multiple IDs); the manifest path is an optional convenience that just reads `<Id>` for you.

# macOS — list everything, do nothing:
./scripts/clear-addin-cache.sh

# Dry-run by ID (preferred), or via the manifest:
./scripts/clear-addin-cache.sh --id <GUID>
./scripts/clear-addin-cache.sh ~/path/to/manifest.xml

# Actually remove (only this ID's files):
./scripts/clear-addin-cache.sh --id <GUID> --apply

# Windows — same flow, registry-scoped:
.\scripts\clear-addin-cache.ps1                  # list, do nothing
.\scripts\clear-addin-cache.ps1 -Id <GUID>       # dry-run
.\scripts\clear-addin-cache.ps1 -Id <GUID> -Apply

Both **dry-run by default** — nothing is removed without `--apply` / `-Apply`. No-args lists every registered add-in so you confirm the ID first. Other add-ins are never affected.

If the ID matches nothing the script says **NOT cleared** and exits non-zero — that means a typo or an already-removed add-in, *not* success. Re-run with no arguments and copy the ID from the list. Don't escalate to a folder-wide wipe on the strength of a miss here.

**Neither script can touch the user's data.** Chat history, skills, MCP registrations, and memory are stored by the WebView, keyed by the origin the add-in is served from — not by add-in ID. On macOS that's a different subtree from the manifests (`Data/Library/WebKit/WebsiteData` vs `Data/Documents/wef`); on Windows the clear script only ever writes to `HKCU`, never to disk. Clearing the manifest by ID is safe to do on a machine whose history matters.

**You must fully restart the Office app after clearing.** Removing the file/registry entry does nothing until the app re-reads it on launch — and a *backgrounded* app counts as still running. Quit **and reopen** Excel / Word / PowerPoin