Troubleshooting

Agent Says “Permission Denied” When Saving Files?

Fix write-failure loops fast and get back to shipping work with a safe, proof-first recovery flow.

If your agent says it can’t write a file because of permission denied, operation not permitted, or read-only file system, you’re usually hitting a path or policy mismatch—not a model-quality issue.

Good news: most write failures resolve in under 5 minutes when you verify the exact path, then test with a tiny canary file in the correct workspace.

What this usually means

You asked the agent to write outside its allowed workspace.
The target folder is read-only or protected by OS/container policy.
The path points to a missing/mis-typed directory.
You are testing in a different session/surface than where file access was configured.

5-minute recovery flow

1) Capture the exact error text

Don’t paraphrase. Save the full message (including path) so you can distinguish permission failure from “file not found” or “wrong workspace.”

2) Verify the target path is inside your workspace

Ask the agent to print the exact absolute path it is trying to write. If it points outside your workspace root, reroute before retrying.

3) Run a tiny canary write

Try writing one tiny file in a known-good folder (like the workspace root or a simple notes/ folder). If canary succeeds, your original path is the blocker.

4) Create missing directories first

If path is valid but nested folders don’t exist, create them before writing. Missing folders often trigger confusing write errors.

5) Require proof of write success

Require: file path, byte size, and first line of content. No proof = not done.

Copy/paste recovery prompt

I’m getting a file write error. Diagnose it step-by-step. 1) Show the exact absolute path you are trying to write. 2) Confirm whether that path is inside this session’s writable workspace. 3) Run a tiny canary write to ./canary-write-test.txt 4) If canary works, create missing directories for my target path and retry once. 5) Return only: - Status - Exact blocker (one sentence) - Evidence (path + file size + first line) Do not claim success without evidence.

High-friction mistakes to avoid

Retry spam: repeating the same failed write burns time and tokens.
Path guesswork: “probably saved” without absolute path proof.
Cross-surface confusion: configuring in one thread, testing in another.
Skipping canary: trying full workflow before proving one tiny write works.

Trust rule: if the agent says “saved,” require exact path + file size + content snippet before moving on.

When to escalate to #help

Escalate after one clean retry if canary and real target both fail. Include:

Exact error text (verbatim)
Attempted absolute target path
Whether canary write passed or failed
Session/surface used (dashboard, DM, server channel, thread)
Timestamp + timezone

Bottom line: treat write failures as path/policy diagnosis, not model failure. One canary write plus path proof resolves most cases quickly.