---
title: "Runtime configuration management"
description: "Weaviate supports runtime configuration management, allowing some configurations to be changed without any further restarts."
url: https://docs.weaviate.io/deploy/configuration/env-vars/runtime-config
---

# Runtime configuration management

> [!NOTE]
>
> **Added in `v1.30`**

Weaviate supports runtime configuration management, allowing some configurations to be changed without any further restarts.

Most runtime configurations correspond to an existing environment variable. When a runtime configuration is updated, it overrides the value set by the corresponding environment variable.

## How to set up runtime configuration

1. **Enable the feature** Set the environment variable `RUNTIME_OVERRIDES_ENABLED` to `true`.

2. **Provide an overrides file** Create a configuration file that contains the runtime overrides and point to it using the `RUNTIME_OVERRIDES_PATH` variable.

   **Example configuration override file**

   overrides.yaml

   ```yaml
   maximum_allowed_collections_count: 8
   autoschema_enabled: true
   async_replication_disabled: false
   ```

3. **Set the update interval** Set the `RUNTIME_OVERRIDES_LOAD_INTERVAL` variable to define how often Weaviate should check for configuration changes (default is `2m`).

4. **Restart the instance** In order to finish the setup, restart your Weaviate instance.

### Configuration variables

The following environment variables are used to control runtime configuration management:

| Variable | Description | Type |
| - | - | - |
| `RUNTIME_OVERRIDES_ENABLED` | If set, the runtime configuration management is enabled. Default: `false` | `boolean` |
| `RUNTIME_OVERRIDES_PATH` | Path of the configuration override file. | `string - file path` |
| `RUNTIME_OVERRIDES_LOAD_INTERVAL` | The interval between reading the configuration override file. Default: `2m` | `string - duration` |

## Available overrides

> [!WARNING]
>
> **An unrecognized key is ignored, not rejected**
>
> Weaviate reads only the keys listed below. Any other key in the overrides file is skipped silently — there is no error and no log entry — so a typo or a key from a newer version leaves the setting at its environment-variable value while the file looks correct. Check spelling against this list, then confirm the change took effect in the logs (see [Configuration changes](https://docs.weaviate.io/deploy/configuration/env-vars/runtime-config#configuration-changes)).

The following overrides are currently supported:

### General

| Runtime override name | Environment variable name |
| - | - |
| `async_replication_disabled` | `ASYNC_REPLICATION_DISABLED` |
| `async_replication_scheduler_workers` | `ASYNC_REPLICATION_SCHEDULER_WORKERS` |
| `async_replication_hashtree_init_concurrency` | `ASYNC_REPLICATION_HASHTREE_INIT_CONCURRENCY` |
| `async_replication_cluster_max_workers` *(removed in `v1.38`)* | `ASYNC_REPLICATION_CLUSTER_MAX_WORKERS` *(removed in `v1.38`)* |
| `autoschema_enabled` | `AUTOSCHEMA_ENABLED` |
| `backup_max_individual_files` | `BACKUP_MAX_INDIVIDUAL_FILES` |
| `debug_endpoints_enabled` | `DEBUG_ENDPOINTS_ENABLED` |
| `default_quantization` | `DEFAULT_QUANTIZATION` |
| `default_sharding_count` | `DEFAULT_SHARDING_COUNT` |
| `default_vector_index` | `DEFAULT_VECTOR_INDEX` |
| `disable_graphql` | `DISABLE_GRAPHQL` |
| `export_default_bucket` | `EXPORT_DEFAULT_BUCKET` |
| `export_default_path` | `EXPORT_DEFAULT_PATH` |
| `export_enabled` | `EXPORT_ENABLED` |
| `export_parallelism` | `EXPORT_PARALLELISM` |
| `grpc_web_enabled` | *(not applicable)* |
| `inverted_sorter_disabled` | `INVERTED_SORTER_DISABLED` |
| `maximum_allowed_collections_count` | `MAXIMUM_ALLOWED_COLLECTIONS_COUNT` |
| `objects_ttl_batch_size` | `OBJECTS_TTL_BATCH_SIZE` |
| `objects_ttl_concurrency_factor` | `OBJECTS_TTL_CONCURRENCY_FACTOR` |
| `objects_ttl_delete_schedule` | `OBJECTS_TTL_DELETE_SCHEDULE` |
| `objects_ttl_pause_duration` | `OBJECTS_TTL_PAUSE_DURATION` |
| `objects_ttl_pause_every_no_batches` | `OBJECTS_TTL_PAUSE_EVERY_NO_BATCHES` |
| `operational_mode` | `OPERATIONAL_MODE` |
| `query_slow_log_enabled` | `QUERY_SLOW_LOG_ENABLED` |
| `query_slow_log_threshold` | `QUERY_SLOW_LOG_THRESHOLD` |
| `replica_movement_minimum_async_wait` | `REPLICA_MOVEMENT_MINIMUM_ASYNC_WAIT` |
| `revectorize_check_disabled` | `REVECTORIZE_CHECK_DISABLED` |
| `tenant_activity_read_log_level` | `TENANT_ACTIVITY_READ_LOG_LEVEL` |
| `tenant_activity_write_log_level` | `TENANT_ACTIVITY_WRITE_LOG_LEVEL` |

### Raft settings

| Runtime override name | Environment variable name |
| - | - |
| `raft_drain_sleep` | `RAFT_DRAIN_SLEEP` |
| `raft_timeouts_multiplier` | `RAFT_TIMEOUTS_MULTIPLIER` |

### Usage tracking

| Runtime override name | Environment variable name |
| - | - |
| `usage_gcs_bucket` | `USAGE_GCS_BUCKET` |
| `usage_gcs_prefix` | `USAGE_GCS_PREFIX` |
| `usage_policy_version` | `USAGE_POLICY_VERSION` |
| `usage_s3_bucket` | `USAGE_S3_BUCKET` |
| `usage_s3_prefix` | `USAGE_S3_PREFIX` |
| `usage_scrape_interval` | `USAGE_SCRAPE_INTERVAL` |
| `usage_shard_concurrency` | `USAGE_SHARD_CONCURRENCY` |
| `usage_verify_permissions` | `USAGE_VERIFY_PERMISSIONS` |

### Authentication

| Runtime override name | Environment variable name |
| - | - |
| `authentication_oidc_certificate` | `AUTHENTICATION_OIDC_CERTIFICATE` |
| `authentication_oidc_client_id` | `AUTHENTICATION_OIDC_CLIENT_ID` |
| `authentication_oidc_groups_claim` | `AUTHENTICATION_OIDC_GROUPS_CLAIM` |
| `authentication_oidc_issuer` | `AUTHENTICATION_OIDC_ISSUER` |
| `authentication_oidc_jwks_url` | `AUTHENTICATION_OIDC_JWKS_URL` |
| `authentication_oidc_scopes` | `AUTHENTICATION_OIDC_SCOPES` |
| `authentication_oidc_skip_client_id_check` | `AUTHENTICATION_OIDC_SKIP_CLIENT_ID_CHECK` |
| `authentication_oidc_username_claim` | `AUTHENTICATION_OIDC_USERNAME_CLAIM` |

### MCP

Added in `v1.38`. Toggling these at runtime does not require a cluster restart: the HTTP handlers stay registered and per-request checks pick up the new value. See [MCP server](https://docs.weaviate.io/weaviate/configuration/mcp-server) for behavior details.

| Runtime override name | Environment variable name |
| - | - |
| `mcp_server_enabled` | `MCP_SERVER_ENABLED` |
| `mcp_server_write_access_enabled` | `MCP_SERVER_WRITE_ACCESS_ENABLED` |

`MCP_SERVER_CONFIG_PATH` is intentionally **not** runtime-configurable, because tool descriptions are baked into the tool schemas at registration.

Refer to the [Environment variables](https://docs.weaviate.io/deploy/configuration/env-vars) page for descriptions on each configuration option

## Operation and monitoring

Runtime configuration is based on tracking configuration file changes, which involves certain operational considerations. If Weaviate attempts to start with an invalid runtime configuration file (e.g., malformed YAML), the process will fail to start and exit.

When modifying the runtime configuration file for a running Weaviate instance, if the new configuration is invalid, Weaviate continues using the last valid configuration that is stored in memory. Error logs and metrics will indicate when configuration loading fails.

### Metrics

Weaviate provides the following [metrics to help you monitor](https://docs.weaviate.io/deploy/configuration/monitoring) runtime configuration status:

| Metric Name | Description |
| - | - |
| `weaviate_runtime_config_last_load_success` | Indicates whether the last loading attempt was successful (`1` for success, `0` for failure) |
| `weaviate_runtime_config_hash` | Hash value of the currently active runtime configuration, useful for tracking when new configurations take effect |

### Logs

Weaviate provides detailed logging to help you monitor runtime configuration changes and troubleshoot issues.

#### Configuration changes

When runtime configuration values are successfully updated, you'll see an `INFO` log. For example:

```text
runtime overrides: config 'MaximumAllowedCollectionsCount' changed from '-1' to '7'  action=runtime_overrides_changed field=MaximumAllowedCollectionsCount new_value=7 old_value=-1
```

#### Configuration validation errors

When an invalid configuration is detected while Weaviate is running, you'll see an `ERROR` log. For example:

```text
loading runtime config every 2m failed, using old config: invalid yaml
```

### Failure modes

A file Weaviate cannot parse at all follows a "fail early, fail fast" principle. A single bad value does not: it is skipped and logged, and the rest of the file still applies. An unrecognized key is not read at all.

**1. Startup with a malformed file** - If Weaviate attempts to start with a runtime configuration file it cannot parse, such as malformed YAML, the process will fail to start and exit. This ensures Weaviate never runs with incorrect settings.

**2. A malformed file during runtime** - When Weaviate is running and the runtime configuration file becomes unparseable:

- Weaviate continues using the last valid configuration stored in memory
- Error logs and metrics indicate the configuration loading failure
- If Weaviate crashes or runs out of memory, it will fail to restart until the configuration is fixed

This design prevents Weaviate from falling back to environment variable defaults when runtime overrides fail, which could lead to unintended behavior or data issues.

Here is an example scenario:

1. Environment variable `MAXIMUM_ALLOWED_COLLECTIONS_COUNT` is set to 10
2. Runtime configuration `MaximumAllowedCollectionsCount` overrides this to 4
3. After some time, the runtime configuration file becomes invalid
4. Weaviate continues using the last valid value (4) while running
5. If Weaviate crashes, it will fail to restart until the configuration file is fixed
6. This prevents starting with the environment default (10), which would be incorrect

This is why it's important to set up monitoring and alerting based on the provided metrics and logs to proactively identify and resolve configuration issues.