perwendel/spark · error · DirectoryTraversalDetection

classpath

Error message

classpath

What it means

DirectoryTraversal.protectAgainstInClassPath guards Spark's static-file serving from the classpath: before mapping a requested URL path onto a local classpath folder, it verifies the resolved location stays within that folder. If the request path escapes the folder (e.g. via ../ sequences), Spark throws DirectoryTraversalDetection with the message "classpath", indicating a blocked directory traversal attempt.

Solutions

1. Locate the request URL that escaped the classpath folder and remove/fix the offending link or client.
2. Keep static file locations shallow and canonical; avoid symlinks or entries pointing outside the resource root.
3. If a scan triggered it, no code change is needed — the protection worked as intended; consider logging/blocking the source.

Path root = Paths.get(localFolder).toAbsolutePath().normalize();
Path candidate = root.resolve(requestPath).normalize();
boolean safe = candidate.startsWith(root);

try {
    DirectoryTraversal.protectAgainstInClassPath(path, localFolder);
} catch (DirectoryTraversalDetection e) {
    respond(403, "Forbidden");
}

When it happens

Trigger: A request for a static classpath resource whose relative path resolves outside the configured classpath local folder, e.g. requesting /../../etc/passwd style paths against staticFiles.location("/public").

Common situations: Security scanners or attackers probing static file endpoints with ../, ..\, or encoded traversal sequences; misconfigured reverse proxies forwarding odd paths; legitimate deep relative links that accidentally escape the resource 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

• external
• Bad request
• WebSocket handler must implement 'WebSocketListener' or be…
• path cannot be null or blank
• httpMethod cannot be null or blank

AI-assisted analysis of perwendel/spark@1973e402f5 (2026-09-10). Data as JSON: /api/errors/aea738fcbbc439ba. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/spark/staticfiles/DirectoryTraversal.java:14

package spark.staticfiles;

import java.nio.file.Paths;

import static spark.utils.StringUtils.removeLeadingAndTrailingSlashesFrom;

/**
 * Protecting against Directory traversal
 */
public class DirectoryTraversal {

    public static void protectAgainstInClassPath(String path, String localFolder) {
        if (!isPathWithinFolder(path, localFolder)) {
            throw new DirectoryTraversalDetection("classpath");
        }
    }

    public static void protectAgainstForExternal(String path, String externalFolder) {
    	String unixLikeFolder = unixifyPath(externalFolder);
        String nixLikePath = unixifyPath(path);
        if (!isPathWithinFolder(nixLikePath, unixLikeFolder)) {
            throw new DirectoryTraversalDetection("external");
        }
    }
    
    private static String unixifyPath(String path) {
    	return Paths.get(path).toAbsolutePath().toString().replace("\\", "/");
    }
    
    private static boolean isPathWithinFolder(String path, String folder) {
    	String rlatsPath = removeLeadingAndTrailingSlashesFrom(path);
    	String rlatsFolder = removeLeadingAndTrailingSlashesFrom(folder);

View on GitHub (pinned to 1973e402f5)