jenkinsci/jenkins · error · IOException

Failed to create a temp file on ${remote}

Error message

Failed to create a temp file on ${remote}

What it means

Thrown by FilePath.createTempFile wrapping any IOException from the remote CreateTempFile callable (which calls File.createTempFile). The message names the remote path so you know which machine/directory failed. Prefix/suffix validation failures and disk/permission errors surface here.

Source

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

    /**
     * Creates a temporary file in the directory that this {@link FilePath} object designates.
     *
     * @param prefix
     *      The prefix string to be used in generating the file's name; must be
     *      at least three characters long
     * @param suffix
     *      The suffix string to be used in generating the file's name; may be
     *      null, in which case the suffix ".tmp" will be used
     * @return
     *      The new FilePath pointing to the temporary file
     * @see File#createTempFile(String, String)
     */
    public FilePath createTempFile(final String prefix, final String suffix) throws IOException, InterruptedException {
        try {
            return new FilePath(this, act(new CreateTempFile(prefix, suffix)));
        } catch (IOException e) {
            throw new IOException("Failed to create a temp file on " + remote, e);
        }
    }

    private static class CreateTempFile extends MasterToSlaveFileCallable<String> {
        private final String prefix;
        private final String suffix;

        CreateTempFile(String prefix, String suffix) {
            this.prefix = prefix;
            this.suffix = suffix;
        }

        private static final long serialVersionUID = 1L;

        @Override
        public String invoke(File dir, VirtualChannel channel) throws IOException {
            File f = File.createTempFile(prefix, suffix, dir);
            return f.getName();

View on GitHub (pinned to 2e228ff40b)

Solutions

1. Ensure prefix is at least 3 characters and contains no path separators.
2. Verify the target directory (this FilePath) exists and is writable on the agent.
3. Free disk space on the agent's relevant volume.
4. Pass a valid suffix or null (defaults to .tmp).

Example fix

// before
fp.createTempFile("a", ".txt"); // prefix too short
// after
fp.createTempFile("prefix", ".txt");

if (prefix == null || prefix.length() < 3 || prefix.contains("/") || prefix.contains("\\")) {
    throw new IllegalArgumentException("invalid temp file prefix: " + prefix);
}

static boolean isValidTempPrefix(String p) {
    return p != null && p.length() >= 3 && !p.contains("/") && !p.contains("\\");
}

try {
    FilePath tmp = fp.createTempFile(prefix, suffix);
} catch (IOException e) {
    // 'Failed to create a temp file' — check disk space, perms, prefix validity
}

When it happens

Trigger: prefix shorter than 3 characters (File.createTempFile requirement); prefix/suffix contain path separators; directory does not exist or is not writable; disk full; too many open files.

Common situations: Passing a short prefix; agent tmp dir full or read-only; workspace on a full volume; concurrent temp-file exhaustion.

Related errors

• Failed to create a temporary directory in ${dir}
• Failed to create a temp directory 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

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