Configuration Reference
All configured engine durations must be positive. Queue, cron task, mutex, and tag names must be nonblank, at most 128 characters, and contain no control characters. Metadata keys and values are non-null strings; they are governed by the serialized job and metadata byte budgets rather than the name limit. Concurrency keys have their own 256-byte UTF-8 limit.
| Setting | Default | Notes |
|---|---|---|
workerCount |
10 |
Workers in the default lane. |
pollInterval |
500ms |
Dispatcher fallback idle poll interval. Scheduled promotion and same-JVM producers sharing a LocalWakeBus can dispatch sooner. |
claimHeartbeat |
15s |
Owner heartbeat refresh cadence. |
maintenancePollInterval |
1s |
Master-only maintenance tick for recurring materialization, scheduled promotion, and orphan reclaim. |
retentionInterval |
1h |
Master-only cadence for retention sweeps: hard-delete of old SUCCEEDED/FAILED/DELETED/QUARANTINED jobs, expired dedup cleanup, and stale node-heartbeat cleanup. |
succeededRetention |
7d |
Age after which SUCCEEDED jobs are hard-deleted. |
failedRetention |
30d |
Age after which FAILED jobs are hard-deleted. |
deletedRetention |
7d |
Age after which DELETED jobs are hard-deleted. |
quarantinedRetention |
30d |
Age after which QUARANTINED jobs are hard-deleted. |
heartbeatTimeout |
60s |
Orphan and node heartbeat expiry. |
maintenanceLeaseDuration |
60s |
Store-backed leadership lease. Must be greater than claimHeartbeat. |
nodeHeartbeatRetention |
10m |
How long old node registry entries remain visible after their last heartbeat. Must be greater than heartbeatTimeout. |
jobTimeout |
5m |
Wall-clock cap per attempt before the first check-in; the worker thread is interrupted when it passes. Handlers see it as ctx.deadline(). |
maxConsecutiveDispatcherFailures |
10 |
Circuit-breaker pause threshold. |
retryInitialBackoff |
5s |
Default retry backoff. |
defaultMaxAttempts |
5 |
Attempts including the first run. |
claimBatchSize |
10 |
Maximum jobs claimed per poll. |
defaultQueue |
default |
Queue a lane-less node polls (the default lane). NOT the queue Scheduler convenience methods write to — those always use the literal "default"; set a matching lane or pass an explicit queue. |
storeOutagePollInterval |
5s |
Probe interval while paused by store outage. |
shutdownGracePeriod |
10s |
Time to wait for in-flight jobs on close. Caps ctx.deadline() while closing; work still running afterwards is interrupted and rescheduled without consuming an attempt. |
checkInMinInterval |
5s |
Minimum interval between persisted check-in/progress/log flushes for one job. |
noProgressTimeout |
15m |
Interrupt deadline after the most recent check-in when a handler stops making progress; replaces jobTimeout once a handler has checked in. |
queueFamilyDiscoveryInterval |
1s |
Core API setting for queue-family discovery cadence. Spring binds this as threadmill.queue-family.discovery-interval. |
queueFamilyRetentionAfterEmpty |
30s |
Core API setting for queue-family empty-queue retention. Spring binds this as threadmill.queue-family.retention-after-empty. |
logMaxRatePerSecond |
100 |
Accepted per-job log entries per second. Extra entries are dropped. |
logMaxEntries |
1000 |
Maximum stored per-job log entries. |
logMaxBytes |
256KB |
Maximum stored per-job log message bytes. |
maxDedupTtl |
30d |
Maximum producer-side deduplication TTL. |
Queue-Family Properties
Section titled “Queue-Family Properties”Spring Boot binds these under threadmill.queue-family.*.
| Setting | Default | Notes |
|---|---|---|
threadmill.queue-family.discovery-interval |
1s |
How often a pattern lane discovers matching enqueued queues and refreshes cached weights. |
threadmill.queue-family.retention-after-empty |
30s |
How long an empty queue remains in a lane working set before being dropped. |
Spring Boot binds most core values directly under threadmill.*, for example
threadmill.worker-count, threadmill.claim-batch-size, and
threadmill.maintenance-lease-duration.
In-Memory Store Property
Section titled “In-Memory Store Property”Spring does not silently select volatile storage. When neither a durable store
nor an application-provided JobStore is available, startup fails unless the
development/test-only in-memory store is explicitly enabled.
| Setting | Default | Notes |
|---|---|---|
threadmill.store.memory.enabled |
false |
Set to true only when losing all jobs on process restart is acceptable. |
PostgreSQL Store Properties
Section titled “PostgreSQL Store Properties”Spring auto-creates a PostgreSQL store when a DataSource bean exists and
threadmill-store-postgres is on the classpath, unless the application defines
its own JobStore bean.
| Setting | Default | Notes |
|---|---|---|
threadmill.store.postgres.schema-mode |
migrate |
migrate, validate, none, or drop-and-migrate. Auto-configured Postgres stores run this action before PostgresJobStore is created. |
threadmill.store.postgres.allow-destructive-schema-reset |
false |
Must be true for drop-and-migrate. This drops only Threadmill-owned schema objects and destroys stored jobs. |
See postgres-schema.md for manual DDL, validation, and reset guidance.
Oracle Store Properties
Section titled “Oracle Store Properties”Spring auto-creates an Oracle store when a DataSource bean exists and
threadmill-store-oracle is on the classpath, unless the application defines
its own JobStore bean or Redis is configured. The application supplies the
Oracle JDBC driver.
| Setting | Default | Notes |
|---|---|---|
threadmill.store.oracle.schema-mode |
migrate |
migrate, validate, none, or drop-and-migrate. Auto-configured Oracle stores run this action before OracleJobStore is created. |
threadmill.store.oracle.allow-destructive-schema-reset |
false |
Must be true for drop-and-migrate. This drops only Threadmill-owned tables and destroys stored jobs. |
threadmill.store.jdbc-type |
postgres or oracle. Needed only when both JDBC store modules are on the classpath and spring.datasource.url does not name the database. Without it, a jdbc:oracle: URL selects Oracle, a jdbc:postgresql: URL selects PostgreSQL, and otherwise the one module present wins (PostgreSQL when both are). |
See oracle-schema.md for privileges, manual DDL, and how interrupted migrations resume.
Redis Store Properties
Section titled “Redis Store Properties”Spring can auto-create a Redis store when threadmill.store.redis.* is set.
| Setting | Default | Notes |
|---|---|---|
threadmill.store.redis.mode |
standalone |
standalone, sentinel, or cluster. |
threadmill.store.redis.uri |
Standalone Lettuce URI; supports rediss:// ACL/TLS configuration and verifyPeer=FULL, CA, or NONE. |
|
threadmill.store.redis.sentinel.master-name |
Sentinel master name. | |
threadmill.store.redis.sentinel.nodes |
Sentinel node list in host:port form. |
|
threadmill.store.redis.sentinel.data-node-username |
Optional Redis data-node ACL username. Requires data-node-password. |
|
threadmill.store.redis.sentinel.data-node-password |
Optional Redis data-node password; supports password-only authentication. | |
threadmill.store.redis.sentinel.sentinel-username |
Optional Sentinel control-plane ACL username. Requires sentinel-password. |
|
threadmill.store.redis.sentinel.sentinel-password |
Optional Sentinel control-plane password; supports password-only authentication. | |
threadmill.store.redis.sentinel.tls |
false |
Use TLS for both Sentinel discovery and Redis data-node connections. Lettuce applies one TLS policy to both. |
threadmill.store.redis.sentinel.verify-mode |
full |
full verifies certificate and hostname, ca verifies only the chain, and none disables verification. Shared by Sentinel and data-node connections. |
threadmill.store.redis.cluster.nodes |
Cluster seed nodes in host:port form. |
|
threadmill.store.redis.cluster.read-policy |
master |
Only master reads are allowed for engine correctness. |
threadmill.store.redis.cluster.username |
Optional Redis Cluster ACL username. Requires password. |
|
threadmill.store.redis.cluster.password |
Optional Redis Cluster password; supports password-only authentication. | |
threadmill.store.redis.cluster.tls |
false |
Use TLS for seed discovery and Cluster node connections. |
threadmill.store.redis.cluster.verify-mode |
full |
full, ca, or none; non-default modes require Cluster TLS. |
threadmill.store.redis.no-eviction-externally-validated |
false |
Set only for managed Redis where CONFIG GET maxmemory-policy is unavailable and operators have verified noeviction out of band. |
threadmill.store.redis.reset-on-start |
false |
Delete all keys under Threadmill’s Redis namespace before creating the auto-configured store. Intended for disposable development environments only. |
threadmill.store.redis.allow-destructive-reset |
false |
Must be true for reset-on-start. This destroys all Threadmill jobs, recurring tasks, dedup records, queue pauses, leases, and concurrency bookkeeping in the Redis namespace. |
Redis Cluster uses one {threadmill} hash slot. See
redis-topologies.md for secure topology examples and
JVM trust-store guidance.
Remote Wake Properties
Section titled “Remote Wake Properties”Remote wake is a latency hint for cross-node workers. Polling remains the correctness fallback.
| Setting | Default | Notes |
|---|---|---|
threadmill.remote-wake.enabled |
true |
Auto-create Postgres LISTEN/NOTIFY or Redis Pub/Sub wake hints for Spring auto-configured durable stores. Oracle, in-memory, and custom stores stay local-wake only unless the application provides a RemoteWakeChannel bean; their other nodes pick up work within poll-interval. |
threadmill.remote-wake.channel |
backend default | Optional channel override. Defaults to threadmill_wake for Postgres and {threadmill}:wake for Redis. Set this when multiple isolated Threadmill deployments share one Postgres database or Redis instance. |
Spring Recurring Properties
Section titled “Spring Recurring Properties”| Setting | Default | Notes |
|---|---|---|
threadmill.spring.enqueue-mode |
after_commit |
after_commit, join_transaction, or immediate. join_transaction is Spring + PostgreSQL or Oracle only. |
threadmill.spring.recurring-namespace |
spring.application.name |
Namespace whose annotation-driven recurring tasks are reconciled at startup. If neither value is set, Threadmill only upserts discovered tasks and does not delete stale ones. |
Initial and lifecycle size budgets
Section titled “Initial and lifecycle size budgets”The JSON serializer reserves up to 16 KiB (one quarter of smaller configured limits) for lifecycle data. With the default 256 KiB maximum, a newly submitted job must fit 240 KiB after normal log and failure-detail trimming. Rejection leaves its version unchanged and writes nothing.
Progress messages are bounded like failure messages. If an attempted job still exceeds the overall encoded byte limit, the serializer progressively compacts optional diagnostics: logs, metadata, result, progress text, and intermediate history. It preserves the work description, identity, current state, ownership, and durable failure decision. This also accounts for JSON escaping overhead. Keep business data in the payload or application store; diagnostics are lossy.
Atomic bulk insert limits
Section titled “Atomic bulk insert limits”All stores accept at most 1,000 jobs and 8 MiB of combined encoded job bodies in
one insertAll call. The capability descriptor exposes both limits. Oversized
batches throw IllegalArgumentException before writing any jobs or adopting
versions. Divide larger submissions into deliberate atomic batches; Threadmill
does not silently split a request whose all-or-nothing semantics you rely on.