Unresolvable `@import` in CLAUDE.md fails completely silently — no warning, and /context shows nothing missing

Status Open
Maintainer reply None cached
Activity 1 comment · opened Aug 22, 2026

Description

In Claude Code, a CLAUDE.md can pull in another markdown file with an @path import, and those imports nest — an imported file's own @ lines are followed too.

Import paths resolve relative to the importing file, not the working directory. That is reasonable. But when a path does not resolve, nothing happens at all: no error, no warning, no "file not found" line, and no indication in /context that anything was expected and missing.

The failure is invisible from every angle:

  • the file exists on disk
  • it opens fine in an editor
  • it is listed in the index file that imports it
  • auditing the directory confirms every file is present and every pointer has a matching filename

All of that can be true while the content was never loaded into the session.

The result is the worst shape a memory bug can take: an assistant that is confidently missing an instruction it believes it has, with the user equally unable to tell. I only found it by asking for a fact that existed solely inside one imported file and getting nothing back.

Reproduction

mkdir -p /tmp/silent-import/memory

cat > /tmp/silent-import/memory/MEMORY.md <<'INNER'
# index
@leaf.md
INNER

cat > /tmp/silent-import/memory/leaf.md <<'INNER'
Secret codename: teal-turtle-7742
INNER

cat > /tmp/silent-import/CLAUDE.md <<'INNER'
# project
@memory/MEMORY.md
INNER

cd /tmp/silent-import
claude -p "If the injected context contains 'Secret codename', answer its value; otherwise answer exactly 'absent'. Do not read any files."
# → teal-turtle-7742   (correct: nested import resolved)

# now break exactly one pointer, in the way that is easiest to write by accident
sed -i '' 's|@leaf.md|@memory/leaf.md|' /tmp/silent-import/memory/MEMORY.md
claude -p "If the injected context contains 'Secret codename', answer its value; otherwise answer exactly 'absent'. Do not read any files."
# → absent   (silently; no warning anywhere, and /context shows nothing missing)

@memory/leaf.md written inside memory/MEMORY.md resolves to memory/memory/leaf.md, which does not exist. It is the intuitive thing to write — the path that is correct from the project root — and it is wrong from inside the imported file.

Two smaller consequences

  1. The wrong base path is very easy to write. From inside an imported index, a sibling must be @name.md; the intuitive @dir/name.md loads nothing.
  2. Because the silence is total, the natural conclusion is that the feature is unsupported. I concluded exactly that twice before finding the real cause. "Feature missing" is a much larger claim than "I called it wrong", and the absence of any diagnostic pushes users toward the larger one.

Expected

Either of these would remove the entire class:

  • a single warning line at load time: import X could not be resolved
  • listing resolved imports in /context, so a user can verify what actually loaded rather than what was requested

The second is strictly better, because it also answers "is my memory actually loaded?" — a question that currently has no reliable answer short of probing for a leaf-only fact.

Environment

  • Claude Code, macOS (Darwin 25.5.0)
  • Nested imports, both from a project CLAUDE.md at the cwd

Related

  • #79046 — ancestor-directory CLAUDE.md imports never being expanded. Different cause, same silence. Both would be caught by a resolved-imports listing in /context.

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗