jenkinsci/jenkins · error · IOException

Failed to create a temp directory on ${remote}

Error message

Failed to create a temp directory on ${remote}

What it means

Thrown by FilePath.createTempDir wrapping IOException from the remote CreateTempDir callable (which calls Files.createTempDirectory). The wrapper names the remote path of this FilePath. CreateTempDir joins prefix and suffix (defaulting suffix to 'tmp') and creates a directory with full Posix permissions on POSIX systems.

Source

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

     *      The suffix string to be used in generating the directory's name; may
     *      be null, in which case the suffix ".tmp" will be used
     * @return
     *      The new FilePath pointing to the temporary directory
     * @since 1.311
     * @see Files#createTempDirectory(Path, String, FileAttribute[])
     */
    public FilePath createTempDir(final String prefix, final String suffix) throws IOException, InterruptedException {
        try {
            String[] s;
            if (suffix == null || suffix.isBlank()) {
                s = new String[]{prefix, "tmp"}; // see File.createTempFile - tmp is used if suffix is null
            } else {
                s = new String[]{prefix, suffix};
            }
            String name = String.join(".", s);
            return new FilePath(this, act(new CreateTempDir(name)));
        } catch (IOException e) {
            throw new IOException("Failed to create a temp directory on " + remote, e);
        }
    }

    private static class CreateTempDir extends MasterToSlaveFileCallable<String> {
        private final String name;

        CreateTempDir(String name) {
            this.name = name;
        }

            private static final long serialVersionUID = 1L;

            @Override
            public String invoke(File dir, VirtualChannel channel) throws IOException {

                Path tempPath;
                final boolean isPosix = FileSystems.getDefault().supportedFileAttributeViews().contains("posix");

View on GitHub (pinned to 2e228ff40b)

Solutions

1. Ensure the target directory (this FilePath) exists and is writable.
2. Free disk space on the agent volume.
3. Keep prefix short and free of path separators / illegal characters.
4. Verify the agent user has permission to create directories and set permissions.

Example fix

null

if (!fp.exists()) fp.mkdirs();
if (!fp.getRemote().equals(remoteValidated)) throw new IllegalArgumentException("bad path");

null

try {
    FilePath d = fp.createTempDir(prefix, suffix);
} catch (IOException e) {
    // 'Failed to create a temp directory' — disk full, perms, or path too long
}

When it happens

Trigger: Parent directory not writable or missing; disk full; prefix contains illegal characters for the filesystem; name too long after joining; permission denied on the target volume.

Common situations: Agent workspace on a read-only/full filesystem; very long prefix+suffix exceeding path limits; container mount not writable; agent user lacks permission.

Related errors

• Failed to create a temp file on ${remote}
• Process working directory '%s' doesn't exist!
• Failed to load {}. The file does not exist
• Failed to load {}. It is not a file
• Failed to unpack %s (%d bytes read)

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