Troubleshooting Library
Find the exact failure first, then follow the narrowest fix for permissions, commands, connections, context limits, or stalled tasks. Each guide includes prevention and links back to the matching error article.
Need the full dictionary? Open the error code library or the shareable common errors cheat sheet.
Permission Denied / File Access Error
Jump to: folder allow-lists, TCC resets, move-file-vs-grant-access.
Context Window Exceeded
Jump to: oversized requests, reset, targeted search, .coworkignore.
MCP Connection Failed
Jump to: process down, port mismatch, curl health check, VPN.
Sub-Agent Timeout
Jump to: hung agents, stop conditions, rate-limit side effects.
Exit Code 127 / Command Not Found
Jump to: which <tool>, absolute PATH, nvm/Homebrew sandbox gaps.
A fixing order that works
When something breaks mid-task, resist the urge to retry immediately. Work down this list and most sessions recover without losing your progress:
- Read the exact failure text. The message names the layer that failed — file access, command not found, tool connection, or limits. Match it to a card above.
- Recall what just changed. New folder access, a renamed path, a restarted machine, or a fresh config explains most sudden failures.
- Apply the narrowest fix. Re-grant one folder, correct one path, restart one process. Avoid throwing away the session when a single grant will do.
- Verify before continuing. Re-run the small step that failed, not the whole task, so you know the fix actually landed.
- Reset only as a last resort. If the session is truly stuck, start fresh — but export the transcript first so the context is not lost.
Three checks before any fix
- Cloud or local? Cloud sessions fail differently from local ones — see cloud vs local sessions if you are unsure which you are running.
- Which exact message? Copy the full error text. Partial recollections send you to the wrong card.
- Reproducible? If it fails every time on the same step, it is configuration; if it is random, suspect limits or timeouts.
When to stop fixing and start over
Some sessions are not worth saving: a context window pushed past its limit several times, a merge conflict loop that has already damaged files, or repeated tool failures after a clean restart. Export what you need from the transcript, restore from backup if files were touched, and start a new session with a tighter scope. The time cost is usually smaller than a long repair fight.
Cannot find what you are looking for?
Check the Getting Started Guide or join the Community for help.