quarkusio/quarkus · error · IllegalStateException

quarkus.rest.client.multipart-buffer-size cannot be lower th

Error message

quarkus.rest.client.multipart-buffer-size cannot be lower than 16384

What it means

This IllegalStateException is thrown in MultiByteHttpData's static initializer when the system property quarkus.rest.client.multipart-buffer-size is set below the default minimum of 16384 bytes. The multipart encoder requires a minimum buffer size to function correctly, so an invalid value fails the class load immediately at first use.

Source

Thrown at independent-projects/resteasy-reactive/client/runtime/src/main/java/org/jboss/resteasy/reactive/client/impl/multipart/MultiByteHttpData.java:81

    private String contentTransferEncoding;

    // TODO: replace with a simple array based?
    // TODO: we do `discardReadBytes` on it which is not optimal - copies array every time
    private final ByteBuf buffer = VertxByteBufAllocator.DEFAULT.heapBuffer(BUFFER_SIZE, BUFFER_SIZE);

    private final Context context;

    private volatile boolean done = false;

    private boolean paused = false;
    private int awaitedBytes;

    static {
        BUFFER_SIZE = Integer
                .parseInt(System.getProperty("quarkus.rest.client.multipart-buffer-size", String.valueOf(DEFAULT_BUFFER_SIZE)));
        if (BUFFER_SIZE < DEFAULT_BUFFER_SIZE) {
            throw new IllegalStateException(
                    "quarkus.rest.client.multipart-buffer-size cannot be lower than " + DEFAULT_BUFFER_SIZE);
        }
    }

    /**
     *
     * @param name name of the parameter
     * @param filename file name
     * @param contentType content type
     * @param contentTransferEncoding "binary" for sending binary files
     * @param charset the charset
     * @param content the Multi to send
     * @param errorHandler error handler invoked when the Multi emits an exception
     * @param context Vertx context on which the data is sent
     * @param resumption the action to execute when the requested amount of bytes is ready, or the Multi is completed
     */
    public MultiByteHttpData(String name, String filename, String contentType,
            String contentTransferEncoding, Charset charset, Multi<Byte> content,

View on GitHub (pinned to e1c734241f)

Solutions

Set quarkus.rest.client.multipart-buffer-size to 16384 or higher
Remove the system property entirely to fall back to the default buffer size
If memory is the goal, tune other limits (e.g. multipart max size) rather than shrinking this buffer

Example fix

// before
java -Dquarkus.rest.client.multipart-buffer-size=4096 -jar app.jar
// after
java -Dquarkus.rest.client.multipart-buffer-size=16384 -jar app.jar

Defensive patterns

Strategy: validation

Validate before calling

int v = Integer.parseInt(System.getProperty("quarkus.rest.client.multipart-buffer-size", "16384"));
if (v < 16384) throw new IllegalStateException("quarkus.rest.client.multipart-buffer-size must be >= 16384");

Try / catch

try {
    // first multipart request triggers class init
    sendMultipartRequest();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("multipart-buffer-size")) {
        throw new IllegalStateException("Fix JVM property quarkus.rest.client.multipart-buffer-size (must be >= 16384)", e);
    }
    throw e;
}

Prevention

Never set quarkus.rest.client.multipart-buffer-size below 16384
Validate JVM flags in startup scripts/container entrypoints
Remove the property entirely if you only need the default behavior
Add a smoke multipart request to startup health checks to catch config errors early

When it happens

Trigger: Starting an application with -Dquarkus.rest.client.multipart-buffer-size=<value less than 16384>; the static block in MultiByteHttpData validates the parsed value and throws during class initialization.

Common situations: Tuning multipart uploads downward to save memory without knowing the floor, copying a property value from a different setting that uses a smaller default, typos producing tiny values, container images baking in an invalid JVM property.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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