> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/temporalio/temporal/llms.txt
> Use this file to discover all available pages before exploring further.

# Dynamic Configuration Reference

> Runtime configuration keys for Temporal Server

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:

```yaml theme={null}
dynamicConfigClient:
  filepath: config/dynamicconfig/development.yaml
  pollInterval: 10s
```

The file contains key-value pairs with optional constraints:

```yaml theme={null}
# 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:

```yaml theme={null}
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:

1. All specified constraints match
2. Fewer constraints specified
3. 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:

```bash theme={null}
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

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

## Example Configuration

```yaml theme={null}
# 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
```

## Troubleshooting

### Config Not Taking Effect

1. Check file path in server configuration
2. Verify poll interval has elapsed
3. Look for validation errors in server logs
4. Ensure constraints match exactly (case-sensitive)

### Performance Issues

1. Review rate limits - they may be too restrictive
2. Check partition counts for high-throughput task queues
3. Adjust concurrency settings for workers
4. Monitor persistence QPS limits

## See Also

* [Server Configuration Reference](/reference/server-config)
* [Performance Tuning Guide](/guides/performance-tuning)
* [Monitoring and Metrics](/guides/monitoring)