zed-industries/zed · error · anyhow::Error

Cannot read file because its path matches the worktree…

Error message

Cannot read file because its path matches the worktree `file_scan_exclusions` setting: {}

What it means

The third gate in the `read_file` tool: after global checks pass, the worktree-level settings are fetched with `WorktreeSettings::get(Some((&project_path).into()), cx)` and the path is tested against `is_path_excluded`. A match against the project's own `file_scan_exclusions` produces this error.

Solutions

Edit the project `.zed/settings.json` and narrow the `file_scan_exclusions` pattern so the needed file is not matched.
Ask the repo owner whether the exclusion is load-bearing before changing committed settings.
Read the file outside the agent (editor/chat paste) if the exclusion must remain.
Verify no global-level pattern also matches, since global gates run first.

Example fix

// .zed/settings.json (project)
// before
{
  "file_scan_exclusions": ["generated"]
}
// after — keep bulky artifacts excluded but let summary files through
{
  "file_scan_exclusions": ["generated/**/*", "!generated/README.md"]
}

Defensive patterns

Strategy: validation

Validate before calling

let worktree = WorktreeSettings::get(Some((&project_path).into()), cx);
if worktree.is_path_excluded(&project_path.path) {
    // worktree-level exclusion: skip the read or request a settings change
}

Try / catch

match read_file(path).await {
    Err(e) if e.to_string().contains("worktree `file_scan_exclusions`") => {
        // project-level policy — surface to the user, don't retry
    }
    rest => rest,
}

Prevention

Review committed `.zed/settings.json` exclusions when onboarding a repo.
Prefer excluding generated subtrees over excluding whole top-level directories.
Use negation/narrow patterns to keep specific files readable when needed.

When it happens

Trigger: The agent reads a path matched by `file_scan_exclusions` in the project's `.zed/settings.json` (checked into the repo, affecting everyone who opens it).

Common situations: A repo commits `.zed/settings.json` excluding `dist/`, `coverage/`, or generated protobuf code; contributors' agents then cannot read those paths. Also hit when the project panel shows the file but the scan excluded it from agent access.

Related errors

AI-assisted analysis of zed-industries/zed@f4178619ac (2026-08-20). Data as JSON: /api/errors/4957a114312b4367. Report an issue: GitHub.

Appendix: source

Thrown at crates/agent/src/tools/read_file_tool.rs:327

                }

                if global_settings.is_path_private(&project_path.path) {
                    anyhow::bail!(
                        "Cannot read file because its path matches the global `private_files` setting: {}",
                        input.path
                    );
                }

                let worktree_settings = WorktreeSettings::get(Some((&project_path).into()), cx);
                if worktree_settings.is_path_excluded(&project_path.path) {
                    anyhow::bail!(
                        "Cannot read file because its path matches the worktree `file_scan_exclusions` setting: {}",
                        input.path
                    );
                }

                if worktree_settings.is_path_private(&project_path.path) {
                    anyhow::bail!(
                        "Cannot read file because its path matches the worktree `private_files` setting: {}",
                        input.path
                    );
                }

                anyhow::Ok(())
            }).map_err(tool_content_err)?;

            if fs.is_dir(&abs_path).await {
                return Err(tool_content_err(format!(
                    "{} is a directory, not a file. Use the list_directory tool to explore directory contents.",
                    input.path
                )));
            }

            if let Some(canonical_target) = &symlink_canonical_target {
                let authorize = cx.update(|cx| {
                    authorize_symlink_access(

View on GitHub (pinned to f4178619ac)