| name | claude-desktop-debug |
| description | Use this skill whenever a user reports any problem with the Claude Desktop application on Windows — including but not limited to: MCP tools or connectors not appearing in chat, extensions not loading (spinner, error badge, nothing shows), app showing a white or blank screen, app crashing on startup or at launch, Claude Desktop running slowly or freezing, models not available or missing from the model picker, authentication failing or looping, extensions, local MCP servers, or remote connectors not working, or any symptom described as "Claude Desktop broke", "my extension stopped working", "the app won't open", "I lost my tools", or "MCP isn't working". Trigger this skill even if the user does not mention MCP, extensions, or connectors by name — focus on the symptom. |
| version | 0.1.0 |
Claude Desktop Diagnostics
You are helping a user diagnose a problem with the Claude Desktop chat application on Windows.
Work through the sections below in order. The decision tree in Section 2 routes to detailed
reference files — read them as needed.
1. Detect Install Type (Do This First)
Claude Desktop is distributed in two ways, and they use different config and log paths. Many
issues — especially "everything stopped working after an update" — trace directly to this. Always
identify the install type before reading any config or logs.
Run this in PowerShell:
Get-AppxPackage -Name "*Claude*" | Select-Object Name, PackageFamilyName
| Result | Install type |
|---|
| Returns a package entry | MSIX (Store / new installer) |
| Returns nothing | Standard (Win32 / old installer) |
Path quick-reference
| Resource | Standard path | MSIX path |
|---|
| Config | %APPDATA%\Claude\claude_desktop_config.json | %LOCALAPPDATA%\Packages\<PFN>\LocalCache\Roaming\Claude\claude_desktop_config.json |
| Logs dir | %APPDATA%\Claude\logs\ | %LOCALAPPDATA%\Packages\<PFN>\LocalCache\Roaming\Claude\logs\ |
Replace <PFN> with the PackageFamilyName from the command above (typically Claude_pzs8sxrjxfjjc).
MSIX path check: Some packaged builds and in-app config actions can resolve different
candidate files. Detect the install type, inspect both existing candidates, and use fresh logs to establish which file the running app loaded.
To resolve the MSIX config path automatically:
$pfn = (Get-AppxPackage -Name "*Claude*").PackageFamilyName
"$env:LOCALAPPDATA\Packages\$pfn\LocalCache\Roaming\Claude\claude_desktop_config.json"
2. Issue Decision Tree
3. Quick Log Triage
Run these in PowerShell to pull the most relevant evidence immediately. Substitute the MSIX path
from Section 1 if needed.
# MCP connection log — shows config errors, server disconnects, JSON parse failures
Get-Content "$env:AppData\Claude\logs\mcp.log" -Tail 30
# Per-server log — replace the name with your server or extension key
Get-Content "$env:AppData\Claude\logs\mcp-server-my-server.log" -Tail 50
# See all log files and their sizes
Get-ChildItem "$env:AppData\Claude\logs\" |
Sort-Object LastWriteTime -Descending |
Select-Object Name, Length, LastWriteTime
An empty or missing logs directory does not prove the install type or that a process never started.
Resolve the install type from Section 1, inspect both candidate log directories, and reproduce once.
Relevant log files:
| Log file | What it records |
|---|
mcp.log | All MCP connections, config load errors, JSON parse failures |
mcp-server-<name>.log | stderr output from that specific server / extension process |
main.log | Main Electron process events |
unknown-remote.log | Cloud / remote session events |
4. Config Validation
A JSON syntax error in claude_desktop_config.json may prevent MCP servers from loading. Validate
every candidate config before reading deeper, then confirm from fresh logs which file was loaded.
# Validate config JSON (Standard path — substitute MSIX path if needed)
Get-Content "$env:AppData\Claude\claude_desktop_config.json" -Raw | ConvertFrom-Json
If this throws an error, the JSON is broken. Common causes:
- Trailing comma —
"args": ["last-item",] — not valid JSON
- BOM (Byte Order Mark) — Notepad on Windows adds an invisible BOM character at the start of
UTF-8 files. It breaks JSON parsers. Re-save the file using VS Code or Notepad++ with encoding
set to "UTF-8 without BOM".
- Unmatched brackets — missing
} or ] when adding a new server entry
A valid minimal config with one MCP server looks like:
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["C:\\path\\to\\server.js"],
"env": {
"API_KEY": "your-key-here"
}
}
}
}
Windows launcher check: if the client reports ENOENT/EINVAL for a command whose
(Get-Command <name>).Source ends in .cmd or .bat, retry through cmd /c:
{
"command": "cmd",
"args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\path\\to\\workspace"]
}
5. Extension Quick Check
For any installed extension:
# Check if extension bundle directories exist
Get-ChildItem "$env:AppData\Claude\" -Filter "dxt-install-*" | Select-Object Name
# Check whether a per-server log was created
Get-ChildItem "$env:AppData\Claude\logs\" -Filter "mcp-server-*" | Select-Object Name
- If no
dxt-install-* directories are found, verify the detected install root before concluding that installation failed. See references/extensions-not-loading.md.
- If no log file exists for the extension, inspect both candidate log directories and
mcp.log; the process may not have launched, the path may differ, or logging may be unavailable.
6. Developer Tools (DevTools)
Check whether DevTools is enabled rather than assuming machine state. If the installed version supports it and developer_settings.json contains allowDevTools: true, try Ctrl+Alt+I inside Claude Desktop.
- Console tab — JavaScript errors from the app renderer; look for red
Error: lines
- Network tab — API calls; look for 4xx/5xx responses that explain auth or model failures
To enable DevTools on a machine where it is not yet enabled:
'{"allowDevTools": true}' | Set-Content "$env:AppData\Claude\developer_settings.json"
Then relaunch Claude Desktop and press Ctrl+Alt+I.
Reference Files
The script scripts/diagnose.ps1 runs a full environment snapshot in one
step — useful when the user just wants to paste something and get results.
