quarkusio/quarkus · error · IllegalArgumentException

Offset + count ( ) larger than file size ( )

Error message

Offset + count (${offset + count}) larger than file size (${fileLength}): ${file}

What it means

PathPart validates that the requested range fits within the file: `offset + count` must not exceed `Files.size(file)`. This IllegalArgumentException is thrown during construction when the byte range extends past the end of the file, ensuring the response never promises more bytes than the file contains.

Solutions

1. Re-read the file size immediately before constructing the part: `long size = Files.size(file); count = Math.min(count, size - offset);`
2. Return 416 Range Not Satisfiable when the requested range exceeds the current file size.
3. Avoid caching file sizes across requests for files that can change; or serve immutable snapshots (copy-on-write).

Example fix

// before
long size = cachedSize; // possibly stale
PathPart part = new PathPart(file, offset, size - offset);
// after
long size = Files.size(file);
if (offset >= size) {
    return Response.status(Response.Status.REQUESTED_RANGE_NOT_SATISFIABLE).build();
}
PathPart part = new PathPart(file, offset, Math.min(requestedCount, size - offset));

long fileSize = Files.size(file);
if (offset >= fileSize) {
    return Response.status(Response.Status.REQUESTED_RANGE_NOT_SATISFIABLE).build();
}
long count = Math.min(requestedCount, fileSize - offset);

boolean fitsInFile(long offset, long count, long fileSize) {
    return offset >= 0 && count >= 0 && offset + count <= fileSize;
}

try {
    return Response.ok(new PathPart(file, offset, count)).build();
} catch (IllegalArgumentException | IOException e) {
    return Response.status(Response.Status.REQUESTED_RANGE_NOT_SATISFIABLE).build();
}

When it happens

Trigger: Calling `new PathPart(file, offset, count)` where offset+count > file size — commonly when the file shrank after its size was cached, or the range was computed against a different/older file, or an overflow made offset+count wrap (caught as too-large or negative count earlier).

Common situations: Caching `Files.size()` from a previous request while the file is being rewritten/truncated; serving files from a live log or rotating file; resume downloads where the server-side file changed between requests; using a stale Content-Length to compute the range.

Related errors

• Count ( ) must be >= 0
• File cannot be read
• File does not exist
• File is not a regular file
• Offset ( ) must be >= 0

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

Appendix: source

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

     * @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 PathPart(Path file, long offset, long count) {
        if (!Files.exists(file))
            throw new IllegalArgumentException("File does not exist: " + file);
        if (!Files.isRegularFile(file))
            throw new IllegalArgumentException("File is not a regular file: " + file);
        if (!Files.isReadable(file))
            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);
        long fileLength;
        try {
            fileLength = Files.size(file);
            if ((offset + count) > fileLength)
                throw new IllegalArgumentException(
                        "Offset + count (" + (offset + count) + ") larger than file size (" + fileLength + "): " + file);
        } catch (IOException e) {
            throw new UncheckedIOException(e);
        }
        this.file = file;
        this.offset = offset;
        this.count = count;
    }
}

View on GitHub (pinned to e1c734241f)