Cannot list directory because its path matches the user's…

Error message

Cannot list directory because its path matches the user's worktree `file_scan_exclusions` setting: {}

What it means

Zed's agent `list_directory` tool refuses to enumerate a directory whose resolved path matches the worktree-level `file_scan_exclusions` setting. This is a deliberate privacy/scan policy: paths excluded from file scanning are also invisible to the agent. The check runs after the global checks, using `WorktreeSettings::get(Some((&project_path).into()), cx)` followed by `is_path_excluded`.

Solutions

Remove or narrow the matching pattern in the worktree `.zed/settings.json` `file_scan_exclusions` array (e.g. replace `"target"` with `"target/debug"` only).
Ask the agent to list a sibling directory that is not excluded, and reference specific files by exact path instead.
If the exclusion is intentional, treat this error as expected behavior and do not retry the same path.
Check the global `file_scan_exclusions` too — the global check fires first, so both levels must permit the path.

Example fix

// .zed/settings.json (worktree settings)
// before
{
  "file_scan_exclusions": ["node_modules"]
}
// after — exclude only a subdirectory so the parent stays listable
{
  "file_scan_exclusions": ["node_modules/.cache"]
}

Defensive patterns

Strategy: validation

Validate before calling

// Before calling the list_directory tool with a path:
let global = WorktreeSettings::get_global(cx);
let worktree = WorktreeSettings::get(Some((&project_path).into()), cx);
if worktree.is_path_excluded(&project_path.path) || global.is_path_excluded(&project_path.path) {
    // skip the call; report the path as scan-excluded
}

Try / catch

// If invoking the tool, treat this bail as a deterministic refusal, not a retryable error:
match list_directory(path).await {
    Err(e) if e.to_string().contains("file_scan_exclusions") => {
        // surface to the user; do not retry the same path
    }
    rest => rest,
}

Prevention

Keep `file_scan_exclusions` patterns narrow; prefer deep specific paths over broad directory names.
Do not ask the agent to explore directories you deliberately excluded.
Test new exclusion globs against paths the agent will need before saving settings.

When it happens

Trigger: The agent (or a test) invokes the `list_directory` tool with a path that matches a pattern in the project's `.zed/settings.json` (or parent `.zed` directory) `file_scan_exclusions` array, e.g. `"target"`, `"node_modules"`, `".git"`, or a glob like `"**/*.env"`.

Common situations: Teams exclude build output, vendored deps, or secret dirs from Zed's file scan; the agent then fails when asked to list them. Adding `target` or `node_modules` to `file_scan_exclusions` then asking the agent to explore those directories is the classic hit.

Related errors

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

Appendix: source

Thrown at crates/agent/src/tools/list_directory_tool.rs:293

                let global_settings = WorktreeSettings::get_global(cx);
                if global_settings.is_path_excluded(&project_path.path) {
                    anyhow::bail!(
                        "Cannot list directory because its path matches the user's global `file_scan_exclusions` setting: {}",
                        input.path
                    );
                }

                if global_settings.is_path_private(&project_path.path) {
                    anyhow::bail!(
                        "Cannot list directory because its path matches the user's 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 list directory because its path matches the user's worktree `file_scan_exclusions` setting: {}",
                        input.path
                    );
                }

                if worktree_settings.is_path_private(&project_path.path) {
                    anyhow::bail!(
                        "Cannot list directory because its path matches the user's worktree `private_paths` setting: {}",
                        input.path
                    );
                }

                let worktree_snapshot = worktree.read(cx).snapshot();
                let Some(entry) = worktree_snapshot.entry_for_path(&project_path.path) else {
                    anyhow::bail!("Path not found: {}", input.path);
                };
                if !entry.is_dir() {
                    anyhow::bail!("{} is not a directory.", input.path);

View on GitHub (pinned to f4178619ac)