alibaba/spring-ai-alibaba · warning · IOException

Path traversal not allowed

Error message

Path traversal not allowed

What it means

GrepSearchTool.validateAndResolvePath() performs the same guard as GlobSearchTool: any search path containing ".." or "~" raises IOException "Path traversal not allowed", preventing content searches outside the tool's root directory.

Source

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

				}
			});

			return results;

		} catch (Exception e) {
			return Collections.emptyMap();
		}
	}

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

View on GitHub (pinned to f82da0b50f)

Solutions

1. Normalize the path argument to a root-relative virtual path (starting with /) before calling.
2. Describe path constraints in the tool schema/description so the model stays within the root.
3. Catch the IOException and return an explanatory tool result so the model retries correctly.
4. Widen rootPath legitimately if users need access beyond the current root.

Example fix

// before
grepTool.search("pattern", "~/notes"); // IOException
// after
grepTool.search("pattern", "/notes");

if (path.contains("..") || path.contains("~")) { throw new IllegalArgumentException("use root-relative paths like /docs"); }

boolean isSafe(String p) { return p != null && !p.contains("..") && !p.contains("~"); }

try { tool.grep(pattern, path); } catch (IOException e) { if (e.getMessage().contains("Path traversal")) { /* surface safe error to model */ } }

When it happens

Trigger: The grep tool receives a path argument from the model or caller containing ".." or "~", e.g. searching "~/.ssh" or "../../../etc".

Common situations: LLM-generated regex/search calls with absolute home paths, prompt-injection exfiltration attempts, callers reusing paths from a differently-rooted tool.

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
• resolved path escapes root directory
• {fieldName} contains unsafe path segment: {segment}
• 非法路径访问尝试: ${path}
• Path traversal not allowed

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