alibaba/spring-ai-alibaba · warning · IOException

Path traversal not allowed

Error message

Path traversal not allowed

What it means

GlobSearchTool.validateAndResolvePath() rejects any virtual path containing ".." or "~" with IOException "Path traversal not allowed". This is a deliberate security guard so file-search tools can never escape the configured root directory.

Source

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

			return "Error: Invalid glob pattern syntax - " + e.getDescription();
		} catch (InvalidPathException e) {
			return "Error: Invalid path format - " + e.getReason();
		} catch (IOException e) {
			return "Error: I/O error - " + e.getMessage();
		} catch (Exception e) {
			return "Error: Unexpected error occurred - " + e.getMessage();
		}
	}

	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 record FileInfo(String path, Instant modifiedTime) {}

	public static Builder builder(String rootPath) {
		return new Builder(rootPath);

View on GitHub (pinned to f82da0b50f)

Solutions

1. Sanitize the requested path before calling the tool: strip .., ~ and make it root-relative.
2. Constrain the model via prompt/tool description to only use paths under the workspace root.
3. Catch IOException and return a safe tool error so the model can retry with a valid path.
4. If legitimate external access is needed, reconfigure the tool's rootPath instead of bypassing the check.

Example fix

// before
String userPath = "../../etc/passwd";
tool.search(userPath); // IOException
// after
String safe = userPath.replace("..", "").replace("~", "");
tool.search(safe.startsWith("/") ? safe : "/" + safe);

function safePath(String p) { if (p.contains("..") || p.contains("~")) throw new IllegalArgumentException("path must stay in workspace"); return p.startsWith("/") ? p : "/" + p; }

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

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

When it happens

Trigger: A tool call (often generated by the LLM) supplies a path like "../../etc/passwd" or "~/secrets" to the glob search tool's path argument.

Common situations: Model hallucinating relative parent paths, users pasting absolute home-directory paths, prompt-injection attempts trying to read files outside the workspace.

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

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