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

Error message

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

What it means

The agent's list_directory tool refuses paths matched by the user's file_scan_exclusions setting; the global scope is checked first (crates/agent/src/tools/list_directory_tool.rs:278) before worktree scope. The error names the setting and the path — it is a deliberate policy guard keeping the agent out of directories the user excluded from scanning, not a malfunction.

Solutions

If the agent should see the directory, remove or narrow the matching glob under file_scan_exclusions in settings.json and retry the request.
List the directory yourself outside the agent and paste or reference the relevant files.
Keep the exclusion but scope the agent's task to specific file paths rather than whole excluded trees.
Narrow the pattern (e.g. root-level node_modules only) so sibling paths stay listable.

Example fix

// settings.json — before
"file_scan_exclusions": ["**/node_modules", "**/dist", "**/target"]

// after (agent needs dist/)
"file_scan_exclusions": ["**/node_modules", "**/target"]

Defensive patterns

Strategy: validation

Validate before calling

// before invoking the tool on a path (tool integrations):
let settings = WorktreeSettings::get_global(cx);
if settings.is_path_excluded(&project_path.path) {
    // tell the user the path is excluded instead of calling the tool
}

Prevention

Review file_scan_exclusions when the agent needs to traverse build outputs.
Prefer narrow exclusion globs over broad ones.
When a listing fails with this message, adjust settings or supply the listing yourself rather than retrying.
Remember worktree-scope exclusions are checked after the global ones with a separate message.

When it happens

Trigger: Asking the agent to list a directory whose path matches a glob in the global file_scan_exclusions of settings.json — e.g. **/node_modules, **/target, **/.git, **/dist, **/build.

Common situations: Users exclude build and dependency directories for performance; the agent is then asked to explore, search, or fix something inside them and the listing is refused with this message.

Related errors

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

Appendix: source

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

                        ResolvedProjectPath::Safe(path) => (path, None),
                        ResolvedProjectPath::SymlinkEscape {
                            project_path,
                            canonical_target,
                        } => (project_path, Some(canonical_target)),
                    })
                }).map_err(|e| e.to_string())?;

            // Check settings exclusions synchronously
            project.read_with(cx, |project, cx| {
                let worktree = project
                    .worktree_for_id(project_path.worktree_id, cx)
                    .with_context(|| {
                        format!("{} is not in a known worktree", input.path)
                    })?;

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

View on GitHub (pinned to f4178619ac)