zed-industries/zed · error

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

Error message

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

What it means

Thrown by the agent's list_directory tool when the requested directory matches a glob in the user's global `file_scan_exclusions` setting. The check reads WorktreeSettings::get_global on the foreground thread before any filesystem access, so scan-excluded directories are deliberately invisible to the agent. This is the first of four settings gates (global exclusions, global private_files, worktree exclusions, worktree private_paths).

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

Solutions

1. Narrow or remove the matching glob in the global `file_scan_exclusions` setting (Zed settings.json), then retry the request
2. Point the agent at a more specific subdirectory the globs do not match
3. If the exclusion is intentional for performance, browse the directory outside the agent (editor file tree or terminal)

Example fix

// before — global settings.json glob blocks the agent
"file_scan_exclusions": ["**/dist/**", "**/examples/**"]

// after — heavy build output stays excluded, examples visible to the agent
"file_scan_exclusions": ["**/dist/**"]

let excluded = project.read_with(cx, |_, cx| {
    WorktreeSettings::get_global(cx).is_path_excluded(&project_path.path)
});
if excluded {
    // skip the list_directory call; report that the path is scan-excluded
}

Match `file_scan_exclusions` in the tool error string and treat it as terminal for that path — report the offending path back to the model instead of retrying with the same input.

When it happens

Trigger: A list_directory tool call whose project path matches any glob in the global `file_scan_exclusions` list (defaults and common user config cover patterns like `**/node_modules`, `**/target`, `**/.git`). Runs before the private_files and worktree-level checks.

Common situations: Asking the agent to explore node_modules, build output, or .git directories that default or user globs cover; a user adds a broad glob like `**/build/**` to settings.json and later forgets it blocks the agent too.

Related errors

• Cannot read file because its path matches the global `file_s
• Invalid model ID {}
• Cannot list directory because its path matches the user's gl
• Cannot list directory because its path matches the user's wo
• output token limit reached

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