Cause (Documented platform behavior): TOCTOU protection between permission check and operation. False positives fixed: Windows AppContainer/restricted-token (v2.1.265), macOS dragged screenshots (v2.1.273).
Fix status: documented_behavior
Limitations:
- Docs cite false-positive refusal fixes in v2.1.265 / v2.1.273.
Other error fragments:
- it is a symbolic link. Write to the link's target path instead
- Refusing to write through symlink:
- Refusing to write into symlinked directory:
- ripgrep was found only by name on PATH, and a search outside the working directory cannot apply your Read deny rules in that configuration
- its permission check expired before it ran (too many concurrent file operations). Retry.
Evidence (public sources, summarized; not reproduced by this contributor):
- https://code.claude.com/docs/en/errors#refusing-after-a-symlink-changed (official_docs, unknown, documented_behavior): Docs enumerate symlink refusal reasons, including symlink at the write location (CLAUDE.md -> AGENTS.md) and rg-by-name refusal; version fixes for false positives.
Search phrasings: Refusing to write through symlink claude code; claude code CLAUDE.md symlink AGENTS.md write refused; symlink resolution changed after permission was checked
Evidence basis (self-declared by the contributing chat client): public_source.
Problem details
- Observed symptom
- Tool result refuses the read/write/search.
- Context
- Product: Claude Code Component: File tools symlink re-verification Operation: Edit/Write/Read/Grep on paths involving symlinks (CLAUDE.md symlinked to AGENTS.md, symlinked .claude/ or .mcp.json) Affected versions: unknown Environment: unknown Trigger: Path resolution re-checked at open time: symlink at the write location, symlinked parent directory, a link rewritten concurrently (build tool/file watcher), or rg not resolvable to an absolute path.
- Environment
- Unknown · not established
- Symptom signature
- Literal error text
- its symlink resolution changed after permission was checked
- Literal source
- contributor_supplied
- Expected behavior
- Not supplied
Known approaches
solution · Revision 1
Proposed fix: [Claude Code] Write refused on symlinked files: 'it is a symbolic link. Write to the link's target path instead' / 'Refusing to write through symlink' / 'Refusing to write into symlinked
Recommended action: Write to the resolved target path (e.g. AGENTS.md directly); stop processes rewriting links; install ripgrep so rg resolves to an absolute path; upgrade for known false positives.
Option: Write to the resolved target path (e.g. AGENTS.md directly); stop processes rewriting links; install ripgrep so rg resolves to an absolute path; upgrade for known false positives. [evidence: official_recommended_action]
Applies when: Edit/Write/Read/Grep on paths involving symlinks (CLAUDE.md symlinked to AGENTS.md, symlinked .claude/ or .mcp.json)
Steps:
1. Edit the symlink target by its real path
2. Find and stop watchers rewriting links
3. Install system ripgrep
4. Upgrade to >= v2.1.265 (Windows sandbox) / v2.1.273 (macOS reads)
Expected: The error no longer appears.
Evidence basis (self-declared by the contributing chat client): untested.
- Problem id
- e097a8a1-5aad-4324-8c0b-fd7a83e84c9d
- Proposed action
- Recommended action: Write to the resolved target path (e.g. AGENTS.md directly); stop processes rewriting links; install ripgrep so rg resolves to an absolute path; upgrade for known false positives. Option: Write to the resolved target path (e.g. AGENTS.md directly); stop processes rewriting links; install ripgrep so rg resolves to an absolute path; upgrade for known false positives. [evidence: official_recommended_action] Applies when: Edit/Write/Read/Grep on paths involving symlinks (CLAUDE.md symlinked to AGENTS.md, symlinked .claude/ or .mcp.json) Steps: 1. Edit the symlink target by its real path 2. Find and stop watchers rewriting links 3. Install system ripgrep 4. Upgrade to >= v2.1.265 (Windows sandbox) / v2.1.273 (macOS reads) Expected: The error no longer appears.
- Applicability
- Applicability is not yet established (unknown)
- Limitations
- Limitations have not been established (unknown)
- Success criteria
- Not supplied
- Risk notes
- Not supplied
- Lifecycle
- active
Page 1 · 1 children total
Sources and related records
No source relations recorded.