What causes "File is not a regular file: ${file}" in quarkusio/quarkus?

Point the FilePart at the actual file inside the directory rather than the directory itself.

quarkusio/quarkus · error · IllegalArgumentException

File is not a regular file: ${file}

Error message

File is not a regular file: ${file}

What it means

FilePart can only send byte ranges of regular files. The constructor rejects anything that exists but is not a regular file (directories, named pipes, special device files) with this IllegalArgumentException.

Source

Thrown at independent-projects/resteasy-reactive/common/runtime/src/main/java/org/jboss/resteasy/reactive/FilePart.java:36

    public final long offset;

    /**
     * The number of bytes to send
     */
    public final long count;

    /**
     * Create a new partial {@link File} object.
     *
     * @param file The file to send
     * @param offset The starting byte of the file (must be >= 0)
     * @param count The number of bytes to send (must be >= 0 and offset+count <= file size)
     */
    public FilePart(File file, long offset, long count) {
        if (!file.exists())
            throw new IllegalArgumentException("File does not exist: " + file);
        if (!file.isFile())
            throw new IllegalArgumentException("File is not a regular file: " + file);
        if (!file.canRead())
            throw new IllegalArgumentException("File cannot be read: " + file);
        if (offset < 0)
            throw new IllegalArgumentException("Offset (" + offset + ") must be >= 0: " + file);
        if (count < 0)
            throw new IllegalArgumentException("Count (" + count + ") must be >= 0: " + file);
        if ((offset + count) > file.length())
            throw new IllegalArgumentException(
                    "Offset + count (" + (offset + count) + ") larger than file size (" + file.length() + "): " + file);
        this.file = file;
        this.offset = offset;
        this.count = count;
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

Point the FilePart at the actual file inside the directory rather than the directory itself.
Validate with Files.isRegularFile(Path) before constructing the part.
If streaming non-regular sources, use a stream/byte-array based part type instead of FilePart.

Example fix

// before
new FilePart(new File(requestDir), 0, count);
// after
new FilePart(new File(requestDir, "payload.bin"), 0, count);

Defensive patterns

Strategy: validation

Validate before calling

Path p = Paths.get(path);
if (!Files.isRegularFile(p)) throw new IllegalStateException("Not a regular file: " + p);

Type guard

static boolean isRegularFile(File f) {
    return f != null && f.isFile();
}

Try / catch

try {
    return new FilePart(file, offset, count);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("File is not a regular file")) {
        throw new IllegalArgumentException("Expected a file, got directory/special file: " + file, e);
    }
    throw e;
}

Prevention

Validate with Files.isRegularFile before constructing parts
Resolve directories to concrete file names before sending
Sanitize user-supplied paths that may point at directories

When it happens

Trigger: new FilePart(file, offset, count) where file.exists() is true but file.isFile() is false — e.g. a File pointing at a directory or a FIFO/socket.

Common situations: Passing a directory because a path variable was meant to point to a file; user-supplied upload path pointing at a directory; platform special files (e.g. /dev entries) used as data sources.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/b28f5c098e60648b. Report an issue: GitHub.