Cannot read file because its path matches the global…

Error message

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

What it means

The agent `read_file` tool refuses to read a file whose path matches the global `file_scan_exclusions` setting (`WorktreeSettings::get_global(cx).is_path_excluded(...)`). Excluded paths are kept out of agent context by design, so reads are blocked with this message naming the offending path. This is the first of four exclusion/privacy checks run synchronously before the file is opened.

Solutions

Remove or narrow the matching pattern in the global Zed settings `file_scan_exclusions` array.
Allow the specific path via a worktree-level setting if your Zed version supports overrides, or move the file out of the matched subtree.
Paste the file contents into the chat directly if a one-off read is needed.
Confirm which pattern matched — test the glob against the path before editing settings.

Example fix

// ~/.config/zed/settings.json (global)
// before
{
  "file_scan_exclusions": ["dist"]
}
// after — only exclude build artifacts, keep sources readable
{
  "file_scan_exclusions": ["dist/*.min.js"]
}

Defensive patterns

Strategy: validation

Validate before calling

if WorktreeSettings::get_global(cx).is_path_excluded(&project_path.path) {
    // globally scan-excluded: skip the read_file call, or ask the user to adjust settings
}

Try / catch

match read_file(path).await {
    Err(e) if e.to_string().contains("global `file_scan_exclusions`") => {
        // deterministic refusal — surface reason, don't retry
    }
    rest => rest,
}

Prevention

Keep global `file_scan_exclusions` minimal; put project-specific excludes in the project's `.zed/settings.json`.
Pre-check candidate paths with `is_path_excluded` when generating read plans in agent code.
Document which globs are global so teammates can trace refusals quickly.

When it happens

Trigger: Invoking the agent's `read_file` tool on a path matched by `file_scan_exclusions` in the user-level global settings (`~/.config/zed/settings.json` on Linux, `~/Library/Application Support/Zed/settings.json` on macOS).

Common situations: Global exclusions for `node_modules`, `target`, `.git`, lockfiles, or large generated files are set once and forgotten; later the agent is asked to read one of those files and fails. Also triggered by over-broad globs that accidentally match source files.

Related errors

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

Appendix: source

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

                            project_path,
                            canonical_target,
                        } => (project_path, Some(canonical_target)),
                    })
                }).map_err(tool_content_err)?;

            let abs_path = project
                .read_with(cx, |project, cx| {
                    project.absolute_path(&project_path, cx)
                })
                .ok_or_else(|| {
                    anyhow!("Failed to convert {} to absolute path", input.path)
                }).map_err(tool_content_err)?;

            // Check settings exclusions synchronously
            project.read_with(cx, |_project, cx| {
                let global_settings = WorktreeSettings::get_global(cx);
                if global_settings.is_path_excluded(&project_path.path) {
                    anyhow::bail!(
                        "Cannot read file because its path matches the global `file_scan_exclusions` setting: {}",
                        input.path
                    );
                }

                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
                    );

View on GitHub (pinned to f4178619ac)