jenkinsci/jenkins · error · IOException

Failed to mkdirs: ${remote}

Error message

Failed to mkdirs: ${remote}

What it means

Thrown by FilePath.mkdirs() when act(new Mkdirs()) returns false, meaning File.mkdirs on the remote/local target failed without throwing (e.g., a parent is a file, or permission denied). The Mkdirs callable also accepts the case where the path already exists, so a false return means creation genuinely could not succeed.

Source

Thrown at core/src/main/java/hudson/FilePath.java:1401

     */
    public @CheckForNull Computer toComputer() {
        Jenkins j = Jenkins.getInstanceOrNull();
        if (j != null) {
            for (Computer c : j.getComputers()) {
                if (getChannel() == c.getChannel()) {
                    return c;
                }
            }
        }
        return null;
    }

    /**
     * Creates this directory.
     */
    public void mkdirs() throws IOException, InterruptedException {
        if (!act(new Mkdirs())) {
            throw new IOException("Failed to mkdirs: " + remote);
        }
    }

    private static class Mkdirs extends MasterToSlaveFileCallable<Boolean> {
        private static final long serialVersionUID = 1L;

        @Override
        public Boolean invoke(File f, VirtualChannel channel) throws IOException, InterruptedException {
            if (mkdirs(f) || f.exists())
                return true;    // OK

            // following Ant <mkdir> task to avoid possible race condition.
            Thread.sleep(10);

            return mkdirs(f) || f.exists();
        }
    }

View on GitHub (pinned to 2e228ff40b)

Solutions

1. Check that no parent component of the path is a file; remove or relocate it.
2. Verify write permission on the agent for the target directory and its parents.
3. Ensure the configured workspace/root path is valid and the mount is writable.
4. Create parent directories with appropriate ownership before invoking mkdirs.

Example fix

null

// before mkdirs, ensure no parent is a file and dirs are writable
Path p = Paths.get(remote);
Files.walk(p.getRoot() == null ? p : p.getRoot())
     .filter(Files::isRegularFile)
     .forEach(f -> { if (p.startsWith(f)) throw new IllegalStateException(f + " is a file blocking mkdirs"); });

null

try {
    fp.mkdirs();
} catch (IOException e) {
    // 'Failed to mkdirs' — verify permissions/parents, then retry or fail soft
}

When it happens

Trigger: A parent path component is a regular file, not a directory; permission denied on a parent; read-only filesystem; path is invalid on the target OS; the target root does not exist and cannot be created.

Common situations: Workspace root configured under a file path; agent running under a user lacking write permission; Docker/container with a read-only mount; Windows path with illegal characters.

Related errors

• Failed to create a temporary directory in ${dir}
• Failed to set the timestamp of ${f} to ${timestamp}
• Failed to delete {0}
• Failed to fully read {0}
• Invalid mode: {}

AI-assisted analysis of jenkinsci/jenkins@2e228ff40b (2026-08-14). Data as JSON: /api/errors/067d4f1e8eab78c1. Report an issue: GitHub.