alibaba/spring-ai-alibaba · warning · IllegalArgumentException

Path traversal not allowed

Error message

Path traversal not allowed

What it means

LocalFilesystemBackend.resolvePath() enforces sandboxing when operating in virtualMode: keys containing '..' or starting with '~' are rejected with IllegalArgumentException("Path traversal not allowed"), before any filesystem access. This prevents reads/writes escaping the virtual root via relative segments.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/extension/file/LocalFilesystemBackend.java:105

	}

	public LocalFilesystemBackend(String rootDir) {
		this(rootDir, false, 10);
	}

	/**
	 * Resolve a file path with security checks.
	 *
	 * When virtualMode=True, treat incoming paths as virtual absolute paths under
	 * cwd, disallow traversal (.., ~) and ensure resolved path stays within root.
	 * When virtualMode=False, preserve legacy behavior: absolute paths are allowed
	 * as-is; relative paths resolve under cwd.
	 */
	private Path resolvePath(String key) throws IllegalArgumentException {
		if (virtualMode) {
			String vpath = key.startsWith("/") ? key : "/" + key;
			if (vpath.contains("..") || vpath.startsWith("~")) {
				throw new IllegalArgumentException("Path traversal not allowed");
			}
			Path full = cwd.resolve(vpath.substring(1)).normalize();
			if (!full.startsWith(cwd)) {
				throw new IllegalArgumentException("Path:" + full + " outside root directory: " + cwd);
			}
			return full;
		}

		Path path = Paths.get(key);
		if (path.isAbsolute()) {
			return path;
		}
		return cwd.resolve(path).normalize();
	}

	@Override
	public List<FileInfo> lsInfo(String path) {
		try {

View on GitHub (pinned to f82da0b50f)

Solutions

1. Remove '..' segments and '~' prefixes from the path before calling the backend.
2. Resolve the path against the intended root and pass the already-normalized absolute path.
3. If escaping the root is legitimately required, disable virtualMode and validate paths at the application layer.
4. Sanitize inputs with FilesystemInterceptor.validatePath() before forwarding to the backend.

Example fix

// before
backend.listFiles("../outside/dir"); // IllegalArgumentException

// after
String key = Paths.get(baseDir).resolve(userInput).normalize().toString();
if (key.contains("..")) throw new IllegalArgumentException("Invalid path");
backend.listFiles(key);

if (key.contains("..") || key.startsWith("~")) {
    throw new IllegalArgumentException("Path traversal not allowed: " + key);
}

boolean isSafeKey(String key) {
    String v = key.startsWith("/") ? key : "/" + key;
    return !v.contains("..") && !v.startsWith("~");
}

try {
    backend.readFile(key);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Path traversal")) {
        throw new SecurityException("Rejected unsafe path: " + key, e);
    }
    throw e;
}

When it happens

Trigger: Calling dirPath/resolvedPath/searchPath/grepRaw (and thus resolvePath) with keys like "../etc/passwd", "a/../../b", or "~/notes.txt" while virtualMode is enabled.

Common situations: LLM/tool-generated file paths that include .. segments; user-supplied paths concatenated into keys; home-directory shorthand (~) assumed to work as in a shell.

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}
• Path: outside root directory:
• 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/2ef73efdb8611a61. Report an issue: GitHub.