Configuration Reference — Quarkus TUS

All configuration properties are under the quarkus.tus prefix.

Build Time Properties

Build time properties are fixed at application build and cannot be changed at runtime.

Property Type Default Description

Property	Type	Default	Description
`quarkus.tus.sse-enabled`	`boolean`	`true`	Whether SSE (Server-Sent Events) endpoints and beans are registered. When disabled, the `/tus/events/{uploadId}` and `/tus/progress/{uploadId}` endpoints are not available.
`quarkus.tus.auth-enabled`	`boolean`	`false`	Whether the authentication filter is registered. When enabled, all TUS endpoints (except OPTIONS) require an authenticated user principal.
`quarkus.tus.rate-limit-enabled`	`boolean`	`false`	Whether the per-client token-bucket throttle is registered. Applies to POST and PATCH only. See Rate Limiting Behind a Proxy before enabling it behind a reverse proxy.
`quarkus.tus.method-override-enabled`	`boolean`	`true`	Whether the `X-HTTP-Method-Override` filter is registered. Required by the TUS core protocol so that clients behind proxies which block `PATCH` and `DELETE` can still upload. Disable it only if something in front of the application enforces rules based on the HTTP method.
`quarkus.tus.path`	`String`	`/tus`	Path prefix used when building `Location` and `Upload-Concat` header values. The endpoints themselves are fixed at `/tus`, so setting this to any other value fails the build. To serve TUS under a different prefix, put the application behind a reverse proxy that rewrites it.

quarkus.tus.sse-enabled

boolean

true

Whether SSE (Server-Sent Events) endpoints and beans are registered. When disabled, the /tus/events/{uploadId} and /tus/progress/{uploadId} endpoints are not available.

quarkus.tus.auth-enabled

boolean

false

Whether the authentication filter is registered. When enabled, all TUS endpoints (except OPTIONS) require an authenticated user principal.

quarkus.tus.rate-limit-enabled

boolean

false

Whether the per-client token-bucket throttle is registered. Applies to POST and PATCH only. See Rate Limiting Behind a Proxy before enabling it behind a reverse proxy.

quarkus.tus.method-override-enabled

boolean

true

Whether the X-HTTP-Method-Override filter is registered. Required by the TUS core protocol so that clients behind proxies which block PATCH and DELETE can still upload. Disable it only if something in front of the application enforces rules based on the HTTP method.

quarkus.tus.path

String

/tus

Path prefix used when building Location and Upload-Concat header values. The endpoints themselves are fixed at /tus, so setting this to any other value fails the build. To serve TUS under a different prefix, put the application behind a reverse proxy that rewrites it.

Note

Authorization is per upload. When quarkus.tus.auth-enabled is true, the principal that created an upload is recorded, and HEAD, PATCH, DELETE and concatenation requests from any other principal are answered with 404 Not Found. Uploads created while auth was disabled have no recorded owner and stay accessible to everyone.

Runtime Properties

Runtime properties can be overridden at startup via application.properties, environment variables, or system properties.

Property Type Default Description

Property	Type	Default	Description
`quarkus.tus.version`	`String`	`1.0.0`	TUS protocol version reported in `Tus-Resumable` and `Tus-Version` response headers.
`quarkus.tus.max-size`	`long`	`107374182400` (100 GB)	Maximum upload size in bytes. Reported in the `Tus-Max-Size` header. Uploads exceeding this size are rejected with 413.
`quarkus.tus.extensions`	`String`	`creation,termination,checksum,expiration,concatenation,concatenation-unfinished,creation-with-upload,creation-defer-length`	Comma-separated list of active TUS protocol extensions. Reported in the `Tus-Extension` header.
`quarkus.tus.expiration-hours`	`long`	`24`	Hours after creation at which an upload expires, reported in `Upload-Expires`. The deadline is set once, when the upload is created, and applies to completed uploads too: an upload that finished but was never collected is removed like any other once its deadline passes. The extension ships primitives, not a destination — an application observes `TusUploadCompletedEvent` and moves the file where it belongs before then. Expired uploads are removed by the expiration scheduler (runs hourly) and on the next HEAD or PATCH that finds them expired (answered with 410). `0` disables expiry: no deadline is recorded and nothing is ever removed for age (the `expiration` extension may then be dropped from `quarkus.tus.extensions`, as no `Upload-Expires` is sent). Negative values fail at boot.
`quarkus.tus.stale-upload-hours`	`long`	`6`	Hours without activity after which an incomplete upload is removed by the stale-upload scheduler (runs hourly), independently of its expiry deadline; activity is any committed chunk. `0` disables the cleanup. Completed uploads are never stale; only `expiration-hours` removes those.
`quarkus.tus.checksum-algorithms`	`String`	`sha1,md5,sha256`	Comma-separated list of supported checksum algorithms. Reported in the `Tus-Checksum-Algorithm` header.
`quarkus.tus.store.local.upload-dir`	`String`	`${java.io.tmpdir}/quarkus-tus-uploads`	Directory where the default local file store writes upload data. Created automatically if it does not exist. The default lives under `java.io.tmpdir`, which the operating system may clean at any time and which is rarely on the volume you want uploads on; a production deployment must set this to a dedicated directory.
`quarkus.tus.max-chunk-size`	`long`	`10485760` (10 MB)	Maximum chunk size per PATCH request in bytes. Enforced on both PATCH uploads and creation-with-upload POST requests. Requests exceeding this limit receive a 413 response. Raising it above 10 MB also requires raising Quarkus’s own body limit, `quarkus.http.limits.max-body-size` (default `10240K`), or the HTTP layer rejects the request before the extension sees it. Chunk bodies stream through the store, so a large chunk does not mean a large heap: the bundled store was measured writing a 400 MB chunk inside a 512 MB heap.
`quarkus.tus.lock-timeout-seconds`	`long`	`30`	Seconds of inactivity after which an upload’s lock is considered abandoned and may be reclaimed. The lock is held for the whole of a chunk transfer and refreshed as bytes arrive, so this only bounds a holder that died or stalled; set it above the longest pause a healthy client may make mid-chunk. A holder whose lock was reclaimed is fenced: anything it still writes, commits or rolls back is refused, so a stalled request that wakes up cannot damage what the reclaimer stored. `0` disables reclamation: a lock is then held until its holder releases it, and a holder that never does leaves the upload locked (423) for good. Negative values fail at boot. Applies to the bundled local file store.
`quarkus.tus.sse-hold-open-timeout-seconds`	`long`	`300`	Seconds a held-open SSE events stream may outlive its upload’s completion before the server closes it anyway. Only affects uploads for which `TusSseService.holdOpen` was called; see SSE. The backstop for a post-upload pipeline that never calls `finish`.
`quarkus.tus.max-concat-parts`	`int`	`1000`	Maximum number of partial uploads a single `Upload-Concat: final` request may reference. Requests exceeding it are rejected with 400. Referencing the same partial more than once is always rejected, regardless of this limit.
`quarkus.tus.rate-limit-requests-per-minute`	`int`	`60`	Sustained request rate allowed per client, for POST and PATCH only.
`quarkus.tus.rate-limit-burst-size`	`int`	`10`	Number of requests a client may make back-to-back before the sustained rate applies.

quarkus.tus.version

String

1.0.0

TUS protocol version reported in Tus-Resumable and Tus-Version response headers.

quarkus.tus.max-size

long

107374182400 (100 GB)

Maximum upload size in bytes. Reported in the Tus-Max-Size header. Uploads exceeding this size are rejected with 413.

quarkus.tus.extensions

String

creation,termination,checksum,expiration,concatenation,concatenation-unfinished,creation-with-upload,creation-defer-length

Comma-separated list of active TUS protocol extensions. Reported in the Tus-Extension header.

quarkus.tus.expiration-hours

long

24

Hours after creation at which an upload expires, reported in Upload-Expires. The deadline is set once, when the upload is created, and applies to completed uploads too: an upload that finished but was never collected is removed like any other once its deadline passes. The extension ships primitives, not a destination — an application observes TusUploadCompletedEvent and moves the file where it belongs before then. Expired uploads are removed by the expiration scheduler (runs hourly) and on the next HEAD or PATCH that finds them expired (answered with 410). 0 disables expiry: no deadline is recorded and nothing is ever removed for age (the expiration extension may then be dropped from quarkus.tus.extensions, as no Upload-Expires is sent). Negative values fail at boot.

quarkus.tus.stale-upload-hours

long

6

Hours without activity after which an incomplete upload is removed by the stale-upload scheduler (runs hourly), independently of its expiry deadline; activity is any committed chunk. 0 disables the cleanup. Completed uploads are never stale; only expiration-hours removes those.

quarkus.tus.checksum-algorithms

String

sha1,md5,sha256

Comma-separated list of supported checksum algorithms. Reported in the Tus-Checksum-Algorithm header.

quarkus.tus.store.local.upload-dir

String

${java.io.tmpdir}/quarkus-tus-uploads

Directory where the default local file store writes upload data. Created automatically if it does not exist. The default lives under java.io.tmpdir, which the operating system may clean at any time and which is rarely on the volume you want uploads on; a production deployment must set this to a dedicated directory.

quarkus.tus.max-chunk-size

long

10485760 (10 MB)

Maximum chunk size per PATCH request in bytes. Enforced on both PATCH uploads and creation-with-upload POST requests. Requests exceeding this limit receive a 413 response. Raising it above 10 MB also requires raising Quarkus’s own body limit, quarkus.http.limits.max-body-size (default 10240K), or the HTTP layer rejects the request before the extension sees it. Chunk bodies stream through the store, so a large chunk does not mean a large heap: the bundled store was measured writing a 400 MB chunk inside a 512 MB heap.

quarkus.tus.lock-timeout-seconds

long

30

Seconds of inactivity after which an upload’s lock is considered abandoned and may be reclaimed. The lock is held for the whole of a chunk transfer and refreshed as bytes arrive, so this only bounds a holder that died or stalled; set it above the longest pause a healthy client may make mid-chunk. A holder whose lock was reclaimed is fenced: anything it still writes, commits or rolls back is refused, so a stalled request that wakes up cannot damage what the reclaimer stored. 0 disables reclamation: a lock is then held until its holder releases it, and a holder that never does leaves the upload locked (423) for good. Negative values fail at boot. Applies to the bundled local file store.

quarkus.tus.sse-hold-open-timeout-seconds

long

300

Seconds a held-open SSE events stream may outlive its upload’s completion before the server closes it anyway. Only affects uploads for which TusSseService.holdOpen was called; see SSE. The backstop for a post-upload pipeline that never calls finish.

quarkus.tus.max-concat-parts

int

1000

Maximum number of partial uploads a single Upload-Concat: final request may reference. Requests exceeding it are rejected with 400. Referencing the same partial more than once is always rejected, regardless of this limit.

quarkus.tus.rate-limit-requests-per-minute

int

60

Sustained request rate allowed per client, for POST and PATCH only.

quarkus.tus.rate-limit-burst-size

int

10

Number of requests a client may make back-to-back before the sustained rate applies.

Extensions and Your Store

quarkus.tus.extensions is a promise made to clients on behalf of whatever UploadStore is installed, and the extension does not check the two against each other at boot. With the bundled local file store every extension works. With a custom store, drop any extension the store cannot honour, because a client that reads it from Tus-Extension will rely on it:

Extension What it needs from the store

Extension	What it needs from the store
`checksum`, `checksum-trailer`	`abortChunk` must genuinely discard staged bytes and leave the offset unchanged — a `460` is only correct if the rejected bytes never count. A store that forwards bytes somewhere it cannot take them back from (see Relaying to another TUS server) should not advertise these.
`concatenation`, `concatenation-unfinished`	A working `concatenate(finalId, sourceIds)`. The method is abstract, so every store has one, but a store whose backend cannot join objects (an implementation that just fails) must not advertise it, or every final `Upload-Concat` request fails after the partials have already been uploaded. The bundled contract test exercises it.
`expiration`	`cleanupExpiredUploads` must actually remove expired uploads, or the `Upload-Expires` header advertises a deadline nothing enforces.
`creation-with-upload`, `creation-defer-length`, `termination`, `creation`	Nothing beyond the base contract; every store gets these from the framework.

checksum, checksum-trailer

abortChunk must genuinely discard staged bytes and leave the offset unchanged — a 460 is only correct if the rejected bytes never count. A store that forwards bytes somewhere it cannot take them back from (see Relaying to another TUS server) should not advertise these.

concatenation, concatenation-unfinished

A working concatenate(finalId, sourceIds). The method is abstract, so every store has one, but a store whose backend cannot join objects (an implementation that just fails) must not advertise it, or every final Upload-Concat request fails after the partials have already been uploaded. The bundled contract test exercises it.

expiration

cleanupExpiredUploads must actually remove expired uploads, or the Upload-Expires header advertises a deadline nothing enforces.

creation-with-upload, creation-defer-length, termination, creation

Nothing beyond the base contract; every store gets these from the framework.

Checksum Trailers

The checksum-trailer extension lets a client send Upload-Checksum as an HTTP trailer, after the body, instead of as a header — useful for clients that stream a large chunk and cannot compute its hash before sending it.

It is not supported and deliberately not advertised, because reading HTTP request trailers requires eclipse-vertx/vert.x#5253, which Vert.x does not yet ship. Clients should send Upload-Checksum as a request header, which is fully supported.

The implementation exists on the checksum-trailer branch, which builds against a patched vertx-core; it will be merged once the upstream change is released.

Rate Limiting Behind a Proxy

Rate limiting is off by default; enable it with quarkus.tus.rate-limit-enabled=true (build time). Clients are identified by the authenticated principal when there is one, and otherwise by the peer address of the connection.

Forwarding headers such as X-Forwarded-For are not trusted by default, because anyone can set them: a client that varied the value per request would get a fresh burst allowance every time and defeat the limiter entirely.

If the application runs behind a reverse proxy, tell Quarkus to resolve the forwarded address, and restrict which peers may do so:

quarkus.http.proxy.proxy-address-forwarding=true
quarkus.http.proxy.trusted-proxies=10.0.0.1

Quarkus verifies the immediate peer is a trusted proxy before rewriting the request’s remote address, and the throttle then applies per forwarded client.

Warning

Without proxy-address-forwarding, every request arriving through a proxy carries the proxy’s address, so all clients share a single bucket and throttle each other. Enable it whenever a proxy sits in front of the application.

Environment Variable Mapping

Quarkus maps configuration properties to environment variables using the standard convention. Replace dots with underscores and convert to uppercase:

export QUARKUS_TUS_MAX_SIZE=1073741824
export QUARKUS_TUS_STORE_LOCAL_UPLOAD_DIR=/var/uploads
export QUARKUS_TUS_EXPIRATION_HOURS=48

Example Configuration

application.properties

# Limit uploads to 1 GB
quarkus.tus.max-size=1073741824

# Store uploads in a dedicated directory
quarkus.tus.store.local.upload-dir=/var/data/uploads

# Remove uploads, finished or not, 12 hours after creation
quarkus.tus.expiration-hours=12

# Only support creation and termination extensions
quarkus.tus.extensions=creation,termination

# Disable SSE progress endpoints
quarkus.tus.sse-enabled=false

# Enable authentication
quarkus.tus.auth-enabled=true