alibaba/spring-ai-alibaba · warning · IllegalArgumentException

Path traversal not allowed:

Error message

Path traversal not allowed: 

What it means

FilesystemInterceptor.validatePath() runs a TRAVERSAL_PATTERN regex over the supplied path and rejects any match (typically "..", leading "~", etc.) with IllegalArgumentException("Path traversal not allowed: <path>"). It is the interceptor-layer guard ensuring normalized, in-bounds paths before backend operations.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/extension/interceptor/FilesystemInterceptor.java:162

		this.tools = Collections.unmodifiableList(toolList);
	}

	public static Builder builder() {
		return new Builder();
	}

	/**
	 * Validate and normalize file path for security.
	 * Prevents directory traversal attacks by checking for ".." and "~".
	 *
	 * @param path The path to validate
	 * @param allowedPrefixes Optional list of allowed path prefixes
	 * @return Normalized canonical path
	 * @throws IllegalArgumentException if path is invalid
	 */
	public static String validatePath(String path, List<String> allowedPrefixes) {
		if (TRAVERSAL_PATTERN.matcher(path).find()) {
			throw new IllegalArgumentException("Path traversal not allowed: " + path);
		}

		// Normalize path
		String normalized = path.replace("\\", "/");
		normalized = Paths.get(normalized).normalize().toString().replace("\\", "/");

		if (!normalized.startsWith("/")) {
			normalized = "/" + normalized;
		}

		// Check allowed prefixes if specified
		if (allowedPrefixes != null && !allowedPrefixes.isEmpty()) {
			boolean hasValidPrefix = false;
			for (String prefix : allowedPrefixes) {
				if (normalized.startsWith(prefix)) {
					hasValidPrefix = true;
					break;
				}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Strip or reject '..' segments and '~' prefixes from user input before calling validatePath().
2. Normalize the path (replace \\ with /, run Paths.get(...).normalize()) yourself, then re-check.
3. Restrict inputs to identifiers resolved server-side rather than raw paths.
4. Return a safe validation error to the caller (e.g. an agent tool 'invalid path' result) instead of propagating the exception.

Example fix

// before
String p = FilesystemInterceptor.validatePath(userInput, prefixes); // throws

// after
String cleaned = userInput.replace("\\", "/");
if (cleaned.contains("..") || cleaned.startsWith("~")) {
    throw new IllegalArgumentException("invalid path from user");
}
String p = FilesystemInterceptor.validatePath(cleaned, prefixes);

if (path == null || TRAVERSAL_PATTERN.matcher(path).find()) {
    throw new IllegalArgumentException("Unsafe path supplied: " + path);
}

boolean passesTraversalCheck(String path) {
    return path != null && !FilesystemInterceptor.TRAVERSAL_PATTERN.matcher(path).find();
}

try {
    String canonical = FilesystemInterceptor.validatePath(path, prefixes);
} catch (IllegalArgumentException e) {
    return Map.of("error", "invalid path", "detail", e.getMessage()); // tool-result style
}

When it happens

Trigger: Calling validatePath(path, allowedPrefixes) with a string containing traversal sequences such as "../../secret", backslash tricks like "..\\..\\x", or "~/file" matching the pattern.

Common situations: Agent/LLM tool calls receiving unsanitized user paths; Windows-style separators slipping past naive checks; legacy code that predates the traversal-pattern guard.

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}
• Path traversal not allowed
• Path must start with one of :
• 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/efde863dbadf3c73. Report an issue: GitHub.