Dynamic Configuration Reference

Dynamic configuration allows you to modify Temporal Server behavior at runtime without restarting services. Configuration is loaded from YAML files and polled periodically for changes.

Configuration File

Dynamic config is defined in a YAML file specified in the server configuration:

dynamicConfigClient:
  filepath: config/dynamicconfig/development.yaml
  pollInterval: 10s

The file contains key-value pairs with optional constraints:

# Global setting
system.forceSearchAttributesCacheRefreshOnRead:
  - value: false

# Namespace-specific setting
history.maxAutoResetPoints:
  - value: 20
    constraints:
      namespace: "my-namespace"

# Task queue specific setting
matching.numTaskqueueWritePartitions:
  - value: 4
    constraints:
      namespace: "prod-namespace"
      taskQueueName: "my-task-queue"

Configuration Format

Each configuration key can have multiple values with different constraints:

keyName:
  - value: <value>
    constraints:
      namespace: "namespace-name"
      namespaceID: "namespace-uuid"
      taskQueueName: "task-queue-name"
      taskType: "activity" # or "workflow"
      shardID: 1
      clusterName: "cluster-name"

Constraint Matching

When retrieving a config value, Temporal uses the most specific matching constraint:

All specified constraints match
Fewer constraints specified
Global default (no constraints)

Key Categories

System Configuration

system.forceSearchAttributesCacheRefreshOnRead

Forces refresh of search attributes cache on read operations.

Type: bool
Default: false
Scope: Global

system.enableGlobalNamespace

Enables global namespace features for multi-cluster replication.

Type: bool
Default: false
Scope: Global

system.enableNamespaceNotFoundDelay

Adds delay for namespace-not-found errors to prevent enumeration attacks.

Type: bool
Default: true
Scope: Global

Frontend Configuration

frontend.rps

Maximum requests per second for the frontend service.

Type: int
Default: 2400
Scope: Global
Constraints: namespace

frontend.namespaceRPS

Per-namespace rate limit for frontend requests.

Type: int
Default: 2400
Constraints: namespace

frontend.maxNamespaceRPSPerInstance

Maximum RPS per namespace per frontend instance.

Type: int
Default: 2400
Constraints: namespace

frontend.globalNamespaceRPS

Global rate limit across all frontend instances for a namespace.

Type: int
Default: 0 (unlimited)
Constraints: namespace

frontend.enableClientVersionCheck

Enables checking client SDK version compatibility.

Type: bool
Default: false
Scope: Global

frontend.disallowQuery

Disables workflow query operations.

Type: bool
Default: false
Constraints: namespace

frontend.shutdownDrainDuration

Duration to drain requests during shutdown.

Type: duration
Default: 0s
Scope: Global

History Configuration

history.rps

Maximum requests per second for history service.

Type: int
Default: 3000
Scope: Global

history.maxAutoResetPoints

Maximum number of auto-reset points to maintain per workflow.

Type: int
Default: 20
Constraints: namespace

history.defaultActivityRetryPolicy

Default retry policy for activities without explicit retry settings.

Type: RetryPolicy
Constraints: namespace

history.defaultWorkflowRetryPolicy

Default retry policy for workflows without explicit retry settings.

Type: RetryPolicy
Constraints: namespace

history.historyCountLimitError

Maximum number of history events before returning an error.

Type: int
Default: 50000
Constraints: namespace

history.historyCountLimitWarn

Warning threshold for number of history events.

Type: int
Default: 10000
Constraints: namespace

history.historySizeLimitError

Maximum total size of history in bytes.

Type: int
Default: 50MB
Constraints: namespace

history.historySizeLimitWarn

Warning threshold for history size.

Type: int
Default: 10MB
Constraints: namespace

history.blobSizeLimitError

Maximum size for individual blobs (events, payloads).

Type: int
Default: 2MB
Constraints: namespace

history.blobSizeLimitWarn

Warning threshold for blob size.

Type: int
Default: 512KB
Constraints: namespace

history.transactionSizeLimit

Maximum size of a single database transaction.

Type: int
Default: 4MB
Scope: Global

history.numPendingActivitiesLimit

Maximum number of pending activities per workflow.

Type: int
Default: 2000
Constraints: namespace

history.numPendingSignalsLimit

Maximum number of pending signals per workflow.

Type: int
Default: 10000
Constraints: namespace

history.numPendingCancelRequestsLimit

Maximum number of pending cancel requests per workflow.

Type: int
Default: 2000
Constraints: namespace

history.numPendingChildExecutionsLimit

Maximum number of pending child workflow executions.

Type: int
Default: 2000
Constraints: namespace

history.replicationTaskFetcherParallelism

Number of parallel workers for fetching replication tasks.

Type: int
Default: 4
Scope: Global

history.enableReplicationTaskBatching

Enables batching of replication tasks for efficiency.

Type: bool
Default: true
Scope: Global

Matching Configuration

matching.numTaskqueueReadPartitions

Number of read partitions for task queues.

Type: int
Default: 4
Constraints: namespace, taskQueueName

matching.numTaskqueueWritePartitions

Number of write partitions for task queues.

Type: int
Default: 4
Constraints: namespace, taskQueueName

matching.forwarderMaxOutstandingPolls

Maximum outstanding poll requests when forwarding.

Type: int
Default: 1
Constraints: namespace, taskQueueName

matching.forwarderMaxOutstandingTasks

Maximum outstanding tasks when forwarding.

Type: int
Default: 1
Constraints: namespace, taskQueueName

matching.forwarderMaxRatePerSecond

Maximum forwarding rate per second.

Type: int
Default: 10
Constraints: namespace, taskQueueName

matching.forwarderMaxChildrenPerNode

Maximum child partitions per parent node.

Type: int
Default: 20
Constraints: namespace, taskQueueName

matching.enableTasklistOwnership

Enables task list ownership for improved isolation.

Type: bool
Default: true
Scope: Global

matching.longPollExpirationInterval

Expiration time for long poll requests.

Type: duration
Default: 1m
Constraints: namespace, taskQueueName

matching.updateAckInterval

Interval for acknowledging task processing.

Type: duration
Default: 1m
Constraints: namespace, taskQueueName

matching.maxTaskQueueIdleTime

Time before idle task queue is unloaded.

Type: duration
Default: 5m
Constraints: namespace, taskQueueName

matching.outstandingTaskAppendsThreshold

Threshold for outstanding task appends before blocking.

Type: int
Default: 250
Constraints: namespace, taskQueueName

Worker Configuration

worker.replicatorConcurrency

Number of concurrent replication workers.

Type: int
Default: 500
Scope: Global

worker.replicationTaskMaxRetryCount

Maximum retries for failed replication tasks.

Type: int
Default: 10
Scope: Global

worker.archiverConcurrency

Number of concurrent archival workers.

Type: int
Default: 50
Scope: Global

worker.archivalsPerIteration

Number of workflows to archive per iteration.

Type: int
Default: 100
Scope: Global

worker.enableAddSearchAttributesFromProto

Enables reading search attributes from proto definitions.

Type: bool
Default: false
Scope: Global

Visibility Configuration

visibility.visibilityArchivalQueryMaxPageSize

Maximum page size for visibility archival queries.

Type: int
Default: 10000
Scope: Global

visibility.enableReadFromClosedExecutionV2

Enables reading from closed execution visibility store.

Type: bool
Default: false
Constraints: namespace

visibility.maxQPS

Maximum queries per second for visibility operations.

Type: int
Default: 1000
Scope: Global

Persistence Configuration

persistence.enablePersistencePriorityRateLimiting

Enables priority-based rate limiting for persistence operations.

Type: bool
Default: false
Scope: Global

persistence.shardUpdateMinInterval

Minimum interval between shard metadata updates.

Type: duration
Default: 5m
Scope: Global

persistence.persistenceMaxQPS

Maximum persistence queries per second.

Type: int
Default: 0 (unlimited)
Scope: Global

persistence.persistenceGlobalMaxQPS

Global maximum persistence QPS across all instances.

Type: int
Default: 0 (unlimited)
Scope: Global

Validation

You can validate dynamic config files before applying them:

temporal-server validate-dynamic-config config/dynamicconfig/production.yaml

This command checks:

Valid YAML syntax
Known configuration keys
Correct value types
Valid constraint names

Best Practices

Start Conservative: Begin with default values and adjust based on monitoring
Test Changes: Validate config files before deploying
Use Constraints: Apply limits per namespace or task queue rather than globally
Monitor Impact: Watch metrics after changing configuration
Document Changes: Comment config files with rationale for custom values
Version Control: Keep dynamic config in version control
Gradual Rollout: For critical changes, use namespace constraints to test with specific workloads first

Example Configuration

# Rate limiting
frontend.namespaceRPS:
  - value: 5000
    constraints:
      namespace: "high-throughput-namespace"
  - value: 100
    constraints:
      namespace: "low-priority-namespace"
  - value: 1000  # default for other namespaces

# History limits
history.historyCountLimitError:
  - value: 100000
    constraints:
      namespace: "long-running-workflows"
  - value: 50000  # default

history.blobSizeLimitWarn:
  - value: 1048576  # 1MB
    constraints:
      namespace: "large-payload-namespace"
  - value: 524288  # 512KB default

# Task queue partitioning
matching.numTaskqueueWritePartitions:
  - value: 16
    constraints:
      namespace: "high-scale-namespace"
      taskQueueName: "main-task-queue"
  - value: 4  # default

# Worker configuration
worker.replicatorConcurrency:
  - value: 1000

# Archival
worker.archiverConcurrency:
  - value: 100

Configuration

CLI Commands

​Configuration File

​Configuration Format

​Constraint Matching

​Key Categories

​System Configuration

​system.forceSearchAttributesCacheRefreshOnRead

​system.enableGlobalNamespace

​system.enableNamespaceNotFoundDelay

​Frontend Configuration

​frontend.rps

​frontend.namespaceRPS

​frontend.maxNamespaceRPSPerInstance

​frontend.globalNamespaceRPS

​frontend.enableClientVersionCheck

​frontend.disallowQuery

​frontend.shutdownDrainDuration

​History Configuration

​history.rps

​history.maxAutoResetPoints

​history.defaultActivityRetryPolicy

​history.defaultWorkflowRetryPolicy

​history.historyCountLimitError

​history.historyCountLimitWarn

​history.historySizeLimitError

​history.historySizeLimitWarn

​history.blobSizeLimitError

​history.blobSizeLimitWarn

​history.transactionSizeLimit

​history.numPendingActivitiesLimit

​history.numPendingSignalsLimit

​history.numPendingCancelRequestsLimit

​history.numPendingChildExecutionsLimit

​history.replicationTaskFetcherParallelism

​history.enableReplicationTaskBatching

​Matching Configuration

​matching.numTaskqueueReadPartitions

​matching.numTaskqueueWritePartitions

​matching.forwarderMaxOutstandingPolls

​matching.forwarderMaxOutstandingTasks

​matching.forwarderMaxRatePerSecond

​matching.forwarderMaxChildrenPerNode

​matching.enableTasklistOwnership

​matching.longPollExpirationInterval

​matching.updateAckInterval

​matching.maxTaskQueueIdleTime

​matching.outstandingTaskAppendsThreshold

​Worker Configuration

​worker.replicatorConcurrency

​worker.replicationTaskMaxRetryCount

​worker.archiverConcurrency

​worker.archivalsPerIteration

​worker.enableAddSearchAttributesFromProto

​Visibility Configuration

​visibility.visibilityArchivalQueryMaxPageSize

​visibility.enableReadFromClosedExecutionV2

​visibility.maxQPS

​Persistence Configuration

​persistence.enablePersistencePriorityRateLimiting

​persistence.shardUpdateMinInterval

​persistence.persistenceMaxQPS

​persistence.persistenceGlobalMaxQPS

​Validation

​Best Practices

​Example Configuration

​Troubleshooting

​Config Not Taking Effect

​Performance Issues

​See Also

Build docs developers (and LLMs) love