quarkusio/quarkus · error · IllegalArgumentException

Offset (${offset}) must be >= 0: ${file}

Error message

Offset (${offset}) must be >= 0: ${file}

What it means

FilePart sends a byte range of a file, so the starting offset must be non-negative. A negative offset would read outside the file's bounds, and the constructor rejects it with this IllegalArgumentException naming both the offset and the file.

Source

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

     */
    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

  1. Clamp the offset to 0 before constructing the FilePart (Math.max(0, offset)).
  2. Fix the upstream arithmetic that produced the negative offset (check the resume/chunk computation).
  3. Validate any user-provided offset input before passing it in.

Example fix

// before
long offset = sentBytes - totalSize;
new FilePart(file, offset, count);
// after
long offset = Math.max(0, sentBytes);
new FilePart(file, offset, count);
Defensive patterns

Strategy: validation

Validate before calling

if (offset < 0) throw new IllegalStateException("Invalid offset " + offset + " for " + file);
FilePart part = new FilePart(file, offset, count);

Type guard

static boolean isValidRange(File f, long offset, long count) {
    return f != null && offset >= 0 && count >= 0 && offset + count <= f.length();
}

Try / catch

try {
    return new FilePart(file, offset, count);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Offset (")) {
        log.warn("Bad offset {} for {}, clamping to 0", offset, file);
        return new FilePart(file, 0, count);
    }
    throw e;
}

Prevention

When it happens

Trigger: new FilePart(file, offset, count) with a negative offset, commonly from an unsigned-offset arithmetic bug or a computed resume position going below zero.

Common situations: Computing offset from a 'resume' marker where bytes-sent was larger than file size; parsing a user-provided range header value without clamping; int/long subtraction underflow when chunking uploads.

Related errors

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