How to Fix Claude Cowork Common Errors (Cheat Sheet)
Published July 9, 2026 · Updated August 12, 2026
Use this page as a shareable error cheat sheet. Match the message you see, then deep-link into the full fix on CoworkHow — symptoms, root cause, step-by-step repair, and prevention.
Cowork sessions are cloud by default. Local folders, shell tools, browsers, and desktop apps still need Claude Desktop open and connected. Permission and PATH failures usually mean the desktop boundary failed — not that “everything stays only on your machine.”
Quick jump table
| Error / symptom | Error article | Troubleshooting guide |
|---|---|---|
| Permission denied / cannot read folder / EACCES | System & Access hub | Permission Denied |
| Exit code 127 / command not found | Tool Execution Failed (127) | Exit Code 127 |
| MCP connection failed / connection refused | System & Access hub | MCP Connection Failed |
| Context window exceeded / request too large | Context & Logic hub | Context Window Exceeded |
| Stale context / reverts earlier fixes | Stale Context Warning | Context Window Exceeded |
| Hallucinated / wrong file paths (ENOENT) | Hallucinated File Paths | Context Window Exceeded |
| Git merge conflict loop | Git Merge Conflict Loop | — |
| NPM ERESOLVE / peer dependency hell | NPM Dependency Hell | — |
| Sub-agent timeout / partial agent results | Workflow & Runtime hub | Sub-Agent Timeout |
| Rate limit exceeded (429) | Rate Limit Exceeded | Sub-Agent Timeout (burst fan-out) |
Full indexes: Error Code Library · Troubleshooting Library
1. Permission denied / “Claude can't read this folder”
Typical messages: Permission denied · Cannot read file at path… · Operation not permitted: EACCES · macOS “Grant access in System Settings → Privacy & Security → Files and Folders.”
What it means: Claude tried to touch a path outside the folders you allowed (or OS privacy settings blocked it). Cloud sessions and account-saved files are separate from Desktop folder access.
Fast fix: Move the file into an already-allowed workspace folder, or re-grant folder access in System Settings / app prompts, then restart Claude Desktop.
Deep dive: Permission Denied troubleshooting · Cloud vs Local Sessions · Security Model
2. Exit code 127 / command not found
Typical messages: Tool execution failed with exit code 127 · npm: command not found · python: command not found
What it means: The shell Cowork used could not find the binary on PATH. Interactive terminals (with nvm/pyenv/Homebrew from .zshrc) often differ from Cowork’s non-interactive environment.
Fast fix: Run which <tool> in your own terminal, then tell Claude the absolute path — or set a project env PATH with absolute directories (no ~).
Deep dive: Tool Execution Failed (127) · Exit Code 127 troubleshooting
3. zsh: permission denied: claude (executable bit / ownership)
Typical messages: zsh: permission denied: claude
What it means: The binary exists but lacks +x, or global npm directories are owned by root.
Fast fix:
chmod +x /path/to/claude
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}
Prefer fixing ownership over installing with sudo. Related: Permission Denied · Exit Code 127
4. MCP connection failed
Typical messages: Failed to connect to MCP server · Connection refused at localhost:… · MCP timeout
What it means: The MCP process is down, bound to a different port, or blocked by VPN/firewall. This is a local networking problem, not a model failure.
Fast fix: Confirm the process with lsof/netstat, match the port in Cowork settings, curl a health check, then retry after quitting and relaunching Desktop.
Deep dive: MCP Connection Failed · Skills and Connectors
5. Context window exceeded vs stale context
Hard limit messages: Request too large · Context window exceeded
Drift symptoms: Claude reverts earlier fixes, asks what file you were on, invents paths.
Fast fix for overflow: Reset/new chat, stop “read everything,” add .coworkignore, prefer search over bulk reads.
Fast fix for drift: Force a fresh file read, or summarize progress and start a new session with that summary.
Deep dive: Context Window Exceeded · Stale Context Warning · Context Loop Pattern · Hallucinated File Paths
Related reading
- Context Loop Pattern — Persistent memory when sessions lose state
- Safety Tips — Habits that prevent permission and file mishaps
- Cloud vs local sessions — Diagnosing tasks that need Desktop open
- Claude Cowork comparisons — When another agent’s workflow avoids a recurring failure mode
- Error Code Library — Deeper per-error troubleshooting
6. Workflow failures: git loops, npm hell, timeouts, 429s
| Failure | Fast move | Full page |
|---|---|---|
| Merge conflict loop | Stop the agent → git merge --abort / rebase --abort → resolve manually | Git Merge Conflict Loop |
| NPM peer / ERESOLVE | Read the conflict → clean install → pin compatible versions (avoid --force) | NPM Dependency Hell |
| Sub-agent hang | Cap concurrency (≤5), add stop-after-N attempts | Sub-Agent Timeout |
| 429 rate limit | Identify RPM vs TPD; wait/backoff or reduce fan-out | Rate Limit Exceeded |
Category hub: Workflow & Runtime Errors
FAQ
When I point Cowork at a working folder, what does that enable?
Desktop folder access lets Claude read/create/edit files there while Claude Desktop stays open and connected. Sessions are cloud-default and files can be saved to your Claude account. Do not assume folder contents never leave your machine. Check plan, org policy, retention, and training settings before using sensitive data.
What is the difference between Cowork and Claude Code?
Claude Code is a developer CLI in the terminal. Claude Cowork is Anthropic’s task mode for multi-step knowledge work (Desktop on macOS/Windows; web/mobile access depends on plan). Local folders, browsers, and desktop apps still need Desktop connected.
Where is the full error dictionary?
Error Code Library for every documented article, and Troubleshooting Library for the guided fix set.
Related reading
- Error Code Library
- Troubleshooting Library
- Cloud vs Local Sessions
- Getting Started
- Security Model
- Context Loop Pattern
- Parallel Task Processing