alibaba/spring-ai-alibaba · warning · IOException

Path outside root directory:

Error message

Path outside root directory: 

What it means

GrepSearchTool confines all searches to a configured root directory. validateAndResolvePath strips the leading '/' from the virtual path, resolves it against rootPath, normalizes it, and throws this IOException when the resolved path no longer starts with rootPath. This is a deliberate security guard against path traversal ('..' segments, symlinks, or absolute paths) escaping the tool's sandboxed workspace.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/tools/GrepSearchTool.java:269

	private Path validateAndResolvePath(String path) throws IOException {
		// Normalize path
		if (!path.startsWith("/")) {
			path = "/" + path;
		}

		// Check for path traversal
		if (path.contains("..") || path.contains("~")) {
			throw new IOException("Path traversal not allowed");
		}

		// Convert virtual path to filesystem path
		String relative = path.substring(1); // Remove leading /
		Path fullPath = rootPath.resolve(relative).normalize();

		// Ensure path is within root
		if (!fullPath.startsWith(rootPath)) {
			throw new IOException("Path outside root directory: " + path);
		}

		return fullPath;
	}

	private boolean isValidIncludePattern(String pattern) {
		if (pattern == null || pattern.isEmpty()) {
			return false;
		}

		// Check for invalid characters
		return !pattern.contains("\0") && !pattern.contains("\n") && !pattern.contains("\r");
	}

	private boolean matchIncludePattern(String filename, String pattern) {
		// Simple glob matching - convert glob to regex
		// This is a simplified version; for production use a proper glob library
		String regex = pattern

View on GitHub (pinned to f82da0b50f)

Solutions

1. Remove any '..' segments or absolute prefixes from the requested path so it stays within the tool's root directory.
2. If the target files legitimately live outside the sandbox, reconfigure GrepSearchTool's root directory to include them (or move/copy them into the workspace).
3. Check for symlinks inside the workspace that resolve outside the root and remove or re-point them.
4. Catch IOException from the tool call and surface the sandbox rule back to the agent so it retries with a relative path.

Example fix

// before
grepTool.search("/../../etc/hosts", "pattern")

// after
grepTool.search("/etc/hosts", "pattern") // only if /etc/hosts is inside the tool's root; otherwise copy it into the workspace first

String p = requestedPath;
if (p.contains("..") || (!p.startsWith("/") && !p.isEmpty())) {
    throw new IllegalArgumentException("Path must be root-relative and stay within the workspace: " + p);
}

boolean isSandboxed(String path, Path root) {
    try {
        return root.resolve(path.replaceFirst("^/", "")).normalize().startsWith(root);
    } catch (Exception e) { return false; }
}

try {
    String hits = grepTool.search(path, pattern);
} catch (IOException e) {
    if (e.getMessage().startsWith("Path outside root directory")) {
        // inform the agent/user that searches are confined to the workspace root
    }
}

When it happens

Trigger: Calling the grep/search tool with a path containing '..' (e.g. '/../../etc'), a path that resolves via symlinks outside the root, or a path that after normalize() lands outside the tool's configured root directory.

Common situations: LLM agents hallucinating absolute filesystem paths like '/etc/passwd' or 'C:\\'; users asking the agent to 'search the parent directory'; workspaces with symlinked subdirectories pointing outside root; misconfigured rootPath narrower than the files being searched.

Understand the failure class

Background: Path traversal blocked: "path escapes the workspace" and "outside site root" errors when a path will not stay inside its allowed directory — this error's family across 26 libraries.

Related errors

• Path traversal not allowed
• Path: outside root directory:
• 非法路径访问尝试: ${path}
• Path traversal not allowed:
• Path traversal not allowed

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/9a037f74e3632245. Report an issue: GitHub.