gradle/gradle · error · IllegalStateException

Unknown file separator: {File.separatorChar}

Error message

Unknown file separator: {File.separatorChar}

What it means

A defensive assertion inside PathTraversalChecker.osIndependentPath: it normalizes '/' and backslash to the platform's File.separatorChar and throws IllegalStateException if the JVM reports any other separator. On every OS Gradle supports (Linux, macOS, Windows) java.io.File.separatorChar is one of those two characters, so this error is effectively unreachable on standard JDKs. Its purpose is to fail loudly on an exotic platform port or a misbehaving FileSystemProvider so the separator gets added to the checker's list rather than silently passed through.

Source

Thrown at platforms/core-runtime/files/src/main/java/org/gradle/internal/file/PathTraversalChecker.java:76

        return containsDirectoryNavigation(name);
    }

    /**
     * We want to treat both '/' and '\' as path separators on all OSes.
     *
     * @param name the original path name
     * @return the path name with all separators replaced with the OS file separator
     */
    private static String osIndependentPath(String name) {
        if (File.separatorChar == '\\') {
            return name.replace('/', File.separatorChar);
        } else if (File.separatorChar == '/') {
            return name.replace('\\', File.separatorChar);
        } else {
            // Throw an error here, as we would want to add this separator to our list
            // rather than passing it through unmodified
            throw new IllegalStateException("Unknown file separator: " + File.separatorChar);
        }
    }

    private static boolean containsDirectoryNavigation(String name) {
        List<String> names = buildNamesList(name);
        for (String part : names) {
            if (part.equals("..")) {
                return true;
            }
            if (IS_WINDOWS) {
                // Directories with dots at the end will have them removed by win32 compatibility
                // We don't know what paths might be directories, so just ban any occurrence of dots at the end
                if (!part.equals(".") && part.endsWith(".")) {
                    return true;
                }
            }
        }
        return false;

View on GitHub (pinned to 534f27719b)

Solutions

1. Print System.getProperty("file.separator") to confirm what the JVM reports
2. Run Gradle on a standard JDK distribution for a supported OS
3. If you maintain the port, add your separator handling to PathTraversalChecker upstream instead of catching and ignoring the error

String sep = System.getProperty("file.separator");
boolean supported = "/".equals(sep) || (sep.length() == 1 && sep.codePointAt(0) == 92);
if (!supported) {
    throw new IllegalStateException("Unsupported file separator on this JVM: " + sep);
}

Catch IllegalStateException and treat it as a fatal environment mismatch - fail fast with the reported separator in the message; retrying cannot help.

When it happens

Trigger: Running Gradle on a JVM where System.getProperty('file.separator') is neither '/' nor a single backslash - an experimental OS port, a custom java.io shim, or a test stub that fakes File.separatorChar.

Common situations: Practically never in production; occasionally surfaced by unit tests that mock java.io.File behavior or by research JVM ports.

Related errors

• Problems opening file input stream for file: {}
• Could not update timestamp for {}
• Failed to create Jar file %s.
• Gradle build daemon disappeared unexpectedly (it may have be
• Unable to create daemon log file

AI-assisted analysis of gradle/gradle@534f27719b (2026-08-22). Data as JSON: /api/errors/ce002ea263b77b06. Report an issue: GitHub.