alibaba/spring-ai-alibaba · error · IllegalArgumentException

Path: outside root directory:

Error message

Path: outside root directory: 

What it means

After resolving and normalizing the requested path, resolvePath verifies the result still starts with the configured root directory (cwd in virtual mode, or the base dir in real mode). If normalization/symlinks or an absolute path moved the result outside the root, it throws "Path:<path> outside root directory". This confines all filesystem tool operations to the sandbox root.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/extension/tools/filesystem/FileSystemTools.java:80

	 */
	public FileSystemTools(String rootDir, boolean virtualMode, int maxFileSizeMb) {
		this.cwd = rootDir != null ? Paths.get(rootDir).toAbsolutePath().normalize() : Paths.get("").toAbsolutePath();
		this.virtualMode = virtualMode;
		this.maxFileSizeBytes = maxFileSizeMb * 1024L * 1024L;
	}

	/**
	 * Resolve a file path with security checks.
	 */
	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();
	}

	// @formatter:off
	@Tool(name = "read_file", description = """
		Reads a file from the filesystem. You can access any file directly by using this tool.
		Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.

		Usage:
		- The file_path parameter must be an absolute path, not a relative path

View on GitHub (pinned to f82da0b50f)

Solutions

1. Use paths relative to the tool's configured root directory.
2. Check the root directory printed in the message and move the target file under it, or reconfigure the tool's root to include the needed path.
3. Remove or replace symlinks that point outside the root; ensure normalization of the real target stays under root.

Example fix

// before
fsTool.read("/var/data/report.csv"); // outside root directory
// after
fsTool.read("data/report.csv"); // relative to the configured root

Path root = Path.of("/path/to/tool/root").toAbsolutePath().normalize();
Path target = root.resolve(userPath).normalize();
if (!target.startsWith(root)) {
    throw new IllegalArgumentException("Path escapes root: " + userPath);
}

static boolean withinRoot(Path root, String userPath) {
    return root.resolve(userPath).normalize().startsWith(root);
}

try {
    fsTool.write(path, content);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("outside root directory")) {
        log.warn("Path {} is outside the tool root; remapping", path);
    }
}

When it happens

Trigger: Passing an absolute path not under the root directory; a path that resolves (including via symlink) outside the root; in non-virtual mode, an absolute Paths.get(key) that is outside the configured base.

Common situations: Hardcoding host-absolute paths like /tmp/data.csv while the tool root is a project sandbox; the root directory configured differently across environments (dev vs container); symlinked directories in the workspace pointing outside the root.

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 outside root directory:
• Elastic search index name must be provided
• Param Not Support Object

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