...

Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).

Motivation

Apache Kafka’s configuration validation is currently version-agnostic. Validation logic is defined in ConfigDef and executed during broker startup, which tightly couples the broker’s static codebase with the cluster’s operational configuration state.

This makes it difficult to strengthen configuration constraints over time. For example, if the minimum allowed value for log.segment.bytes is increased (e.g., from 1 byte to 3 MB), brokers with legacy values in server.properties will fail to start after a binary upgrade due to a ConfigException. Because the broker cannot join the cluster, administrators cannot use dynamic APIs such as AlterConfigs to fix the configuration and must instead manually update configuration files across the fleet.

To address the limitations of the current static, version-agnostic validation model, Kafka needs a mechanism to enforce configuration constraints tied to metadata.version. As Kafka evolves, configuration values that were previously valid may become unsafe or semantically incorrect in newer versions. Without version-aware validation, two issues arise:

1. Unsafe metadata version upgrades: administrators may upgrade metadata.version without realizing that existing configurations violate new constraints.

2. No Metadata-version-aware enforcement: administrators can still use AlterConfigs or IncrementalAlterConfigs to set values that violate constraints introduced in newer metadata versions.

...