/debug

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
Add-in shows "Connection failed"	Read the error paste
Add-in doesn't appear in Excel/PowerPoint at all	Add-in not visible
Want to test/iterate a manifest locally before deploying	Sideload a manifest for local debugging
Sign-in popup fails or loops	Admin consent
Need to see the browser console	Opening browser devtools

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.
• 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
• Windows: 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.

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 / PowerPoint, confirming no lingering process first: pkill -f "Microsoft Excel" (macOS) / check Task Manager (Windows). The script also prints this reminder when it finishes.

Deleting local/sideloaded manifests by ID is safe and works. In practice, removing just the one add-in's file (macOS) or registry value (Windows) cleanly drops that add-in and leaves the rest loading normally — we do this routinely. Microsoft's "don't delete individual files" warning is about a different cache (below), not these local dev/sideload entries; don't let it scare you off the surgical path here.

Centrally-deployed (Admin Center) staleness on Windows is a different cache: %LOCALAPPDATA%\Microsoft\Office\16.0\Wef\<guid>\…, stored under opaque hashes, not by add-in ID. Microsoft's official guidance is conservative — clear that folder's contents as a whole because "deleting individual manifest files can cause all add-ins to stop loading." In practice targeted deletion there can work too, but the filenames aren't ID-mapped so it's hard to be surgical — which is why these scripts deliberately do not touch it. If a centrally-deployed update is stale, prefer waiting out the service TTL or redeploying with a fresh <Id> (below) over hand-deleting that cache.

If it's still stale after the restart, the service-side cache hasn't caught up. Wait, or use a fresh <Id> (below).

Microsoft's cache-clear doc: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/clear-cache

Nuclear option: redeploy with a fresh Id

If 72h is unacceptable, a fresh <Id> UUID forces Admin Center and every client to treat it as a brand-new add-in (24h fresh-deploy SLA, usually much faster). Edit manifest.xml, replace the text inside <Id> with a new UUID (uuidgen on mac/linux, [guid]::NewGuid() in PowerShell), re-upload.

---

Add-in not visible

• Not in the ribbon: Check M365 Admin Center → Integrated apps → your add-in → Users tab. Is the user (or their group) assigned? Nested groups aren't supported.
• Shows "My Add-ins" but not the ribbon button: The manifest's <Hosts> may not include this app. Check both <Hosts> lists (top-level and under <VersionOverrides>).
• Fresh deploy, been <24h: Normal. Microsoft's SLA is 24h for first-time deployment visibility.

---

Sideload a manifest for local debugging

For iterating on a manifest without going through Admin Center deployment (no 24–72h cache wait), point Office at a local manifest file directly. The manifest stays wherever it is on disk; you just tell Office where to find it. Pick the recipe for the customer's OS.

Use the helper scripts — they read the <Id> from the manifest and install it the right way per platform (macOS: a <Id>.manifest.xml file in each app's Documents/wef; Windows: a registry value under HKCU:\SOFTWARE\Microsoft\Office\16.0\Wef\Developer named by the <Id>). Both do direct file/registry writes — not office-addin-dev-settings.

• macOS install: scripts/sideload-addin.sh
• Windows install: scripts/sideload-addin.ps1
• Remove (either OS): clear-addin-cache.{sh,ps1} — see Force a client-side refresh

# macOS — installs directly:
./scripts/sideload-addin.sh ~/path/to/manifest.xml

# Windows — installs directly:
.\scripts\sideload-addin.ps1 C:\path\to\manifest.xml

Sideloading is additive and idempotent, so it installs directly — no dry-run (unlike the destructive clear-addin-cache, which stays dry-run by default). The install names the entry by the add-in <Id>, so removal later is the exact inverse: clear-addin-cache.{sh,ps1} --id <GUID> --apply (the sideload script prints the precise remove command on completion).

Then fully quit and reopen Excel / Word / PowerPoint — check Task Manager (Windows) / pkill -f "Microsoft Excel" (macOS) first; a backgrounded app won't re-read the registry or rescan the folder. The add-in appears under Insert → My Add-ins (Windows also shows it on the Home tab / Shared Folder group); pin it.

Notes (both platforms):

• This is per-user and per-machine — it doesn't touch tenant deployment. It's purely for the customer to debug/iterate on their own box.
• A locally sideloaded manifest wins over a centrally deployed one with the same <Id>, so this is also a fast way to test a manifest fix before re-uploading to Admin Center.
• Pair this with browser devtools to see console/network while iterating.
• If a stale copy keeps loading, also clear the cache — see Force a client-side refresh.

Microsoft's sideloading references:

• Windows: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/create-a-network-shared-folder-catalog-for-task-pane-and-content-add-ins
• macOS: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/sideload-an-office-add-in-on-mac

---

Admin consent

If the user sees a sign-in popup that closes immediately or loops, the tenant hasn't granted admin consent to the Claude app. Run :consent to generate the consent URL for a Global Admin to approve. The symptom in error pastes: user_canceled in the raw error (the broker maps any unclassifiable close to that).

---

Silent SSO / Entra token failures

• AADSTS50194: …not configured as a multi-tenant application / Use a tenant-specific endpoint — your graph_client_id (or the entra_scope resource app) is a single-tenant app, and the add-in build is old enough to still request tokens against the /common authority. Newer builds resolve a tenant-specific authority automatically when graph_client_id is set. Fix: have users update to the latest add-in version. There is no manifest workaround on an old build.
• entra_scope requires graph_client_id — entra_scope was set without graph_client_id. Custom-scope access tokens must be issued by your own Entra app, not the default; set both. The build script also rejects this pairing.
• Silent SSO fails, then an interactive popup works — expected on first run before a service principal exists in the tenant. Once admin consent is granted (see above) the silent path succeeds.

---

Opening browser devtools on the add-in

When you need the WebView's console — JS errors, network tab, the add-in's debug logs — you have to attach the host OS's browser devtools. The add-in runs in an embedded WebView with no address bar and no built-in F12, so each OS has its own recipe.

macOS (Safari Web Inspector)

Three gates. Gate 3 is the one everyone misses.

1. Office developer extras — quit the app first, then:

   defaults write com.microsoft.Excel OfficeWebAddinDeveloperExtras -bool true
   defaults write com.microsoft.Powerpoint OfficeWebAddinDeveloperExtras -bool true
   defaults write com.microsoft.Word OfficeWebAddinDeveloperExtras -bool true
   

   Makes right-click → Inspect Element appear inside the task pane.

2. Safari Develop menu — Safari → Settings → Advanced → check Show features for web developers.

3. macOS Developer Tools allowlist (Sonoma and later) — System Settings → Privacy & Security → Developer Tools → toggle Terminal on. Without this, Safari's Develop menu shows "No Inspectable Applications" even with gates 1 and 2 open.

With the task pane open, either right-click inside it → Inspect Element, or go to Safari → Develop → [your machine name] → find the add-in host (pivot.claude.ai in prod, your configured domain otherwise).

Gotchas:

• Office updates silently reset gate 1. If inspection worked last week and doesn't now, re-run the defaults write.
• "No Inspectable Applications" = gate 3 missing, or the Office app wasn't fully quit before defaults write. pkill -f "Microsoft Excel" then relaunch.
• The task pane has to be open (not just the app) for it to appear under Safari's Develop menu.

Windows (Edge DevTools)

Depends on which WebView engine Office is using. Current M365 on Win10/11 with the WebView2 runtime gets Chromium; older perpetual Office or machines without the runtime may still be on IE11/Trident.

WebView2 (Chromium — the common case):

Right-click inside the task pane → Inspect. That's it, no gates. If right-click doesn't show Inspect, install Microsoft Edge DevTools Preview from the Microsoft Store — it lists all attachable WebView2 targets including Office add-ins. Launch it, find the add-in's URL in the target list, click to attach.

IE11/Trident (legacy Office 2019/2021 perpetual):

Run the IEChooser from an admin PowerShell:

& "C:\Windows\SysWOW64\F12\IEChooser.exe"

Pick the add-in's page from the list. If the list is empty, the task pane isn't open yet — open it first, then refresh IEChooser.

Microsoft's walkthrough: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/debug-add-ins-using-devtools-edge-chromium