Skip to content

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.

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.

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.

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.

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.

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 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.
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.

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.

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.