Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix CLAUDE.md: @ file import fails silently for paths containing spaces (e.g. iCloud Drive on macOS)

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…

The @ file import syntax in CLAUDE.md silently fails when the path contains spaces. No error or warning is shown — the file is simply not loaded.

Error Message

The @ file import syntax in CLAUDE.md silently fails when the path contains spaces. No error or warning is shown — the file is simply not loaded. Actual: The file is silently not loaded. No error or warning is displayed.

Root Cause

The @ file import syntax in CLAUDE.md silently fails when the path contains spaces. No error or warning is shown — the file is simply not loaded.

Fix Action

Workaround

Creating a symlink to a space-free path works around the issue:

ln -s ~/Library/Mobile\ Documents/com~apple~CloudDocs/my-project ~/.my-project

Then use @~/.my-project/_index.md in CLAUDE.md.

Code Example

~/Library/Mobile Documents/com~apple~CloudDocs/

---

@~/Library/Mobile Documents/com~apple~CloudDocs/my-project/_index.md

---

ln -s ~/Library/Mobile\ Documents/com~apple~CloudDocs/my-project ~/.my-project
RAW_BUFFERClick to expand / collapse

Summary

The @ file import syntax in CLAUDE.md silently fails when the path contains spaces. No error or warning is shown — the file is simply not loaded.

Environment

  • Platform: macOS
  • Shell: zsh
  • Claude Code version: latest

Reproduction

  1. On macOS, iCloud Drive files are stored at a path with spaces:

    ~/Library/Mobile Documents/com~apple~CloudDocs/

  2. Add the following to ~/.claude/CLAUDE.md:

    @~/Library/Mobile Documents/com~apple~CloudDocs/my-project/_index.md

  3. Start a new Claude Code session.

  4. Expected: The referenced file is loaded into context at session start. Actual: The file is silently not loaded. No error or warning is displayed.

Impact

This makes it impossible to use @ imports for any files stored on iCloud Drive without a workaround, since iCloud Drive's filesystem path always contains a space (Mobile Documents).

Workaround

Creating a symlink to a space-free path works around the issue:

ln -s ~/Library/Mobile\ Documents/com~apple~CloudDocs/my-project ~/.my-project

Then use @~/.my-project/_index.md in CLAUDE.md.

Suggested Fix

  • Support paths with spaces in `@` imports (treat the entire rest of the line as the path, or support quoted paths: `@"path with spaces/file.md"`)
  • Alternatively, emit a warning when an `@` import path cannot be resolved, so the failure is not silent

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#callback error#memory management#API rate limit#retriever error#indexing error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING