# Broker Configuration Reference

This page lists the supported broker configuration for WarpStream. Configuration not listed here is either ignored (for non-WarpStream keys) or rejected (for unknown `warpstream.*` keys).

Configuration items that start with `warpstream.` are WarpStream-specific. Some native Kafka tooling may not handle these configs as expected.

Broker config in WarpStream is cluster-scoped: `DescribeConfigs` using an empty broker name or a concrete broker ID reflects the same effective cluster configuration.

#### auto.create.topics.enable <a href="#autocreatetopicsenable" id="autocreatetopicsenable"></a>

Whether topics can be auto-created when clients reference unknown topic names.

| Type:         | string (boolean) |
| ------------- | ---------------- |
| Default:      | true             |
| Valid Values: | \[true, false]   |

#### delete.topic.enable <a href="#deletetopicenable" id="deletetopicenable"></a>

Whether topic deletion is allowed.

| Type:         | string (boolean) |
| ------------- | ---------------- |
| Default:      | true             |
| Valid Values: | \[true, false]   |

#### group.consumer.heartbeat.interval.ms <a href="#groupconsumerheartbeatintervalms" id="groupconsumerheartbeatintervalms"></a>

Heartbeat interval for modern (KIP-848) consumer groups.

| Type:         | int                                         |
| ------------- | ------------------------------------------- |
| Default:      | 5000                                        |
| Valid Values: | \[1,2147483647] with cross-validation rules |

#### group.consumer.max.heartbeat.interval.ms <a href="#groupconsumermaxheartbeatintervalms" id="groupconsumermaxheartbeatintervalms"></a>

Upper bound for modern-group heartbeat interval.

| Type:         | int                                         |
| ------------- | ------------------------------------------- |
| Default:      | 15000                                       |
| Valid Values: | \[1,2147483647] with cross-validation rules |

#### group.consumer.max.session.timeout.ms <a href="#groupconsumermaxsessiontimeoutms" id="groupconsumermaxsessiontimeoutms"></a>

Upper bound for modern-group session timeout.

| Type:         | int                                         |
| ------------- | ------------------------------------------- |
| Default:      | 60000                                       |
| Valid Values: | \[1,2147483647] with cross-validation rules |

#### group.consumer.max.size <a href="#groupconsumermaxsize" id="groupconsumermaxsize"></a>

Maximum allowed size for modern (KIP-848) consumer groups.

| Type:         | int             |
| ------------- | --------------- |
| Default:      | 32000           |
| Valid Values: | \[1,2147483647] |

#### group.consumer.min.heartbeat.interval.ms <a href="#groupconsumerminheartbeatintervalms" id="groupconsumerminheartbeatintervalms"></a>

Lower bound for modern-group heartbeat interval.

| Type:         | int                                         |
| ------------- | ------------------------------------------- |
| Default:      | 5000                                        |
| Valid Values: | \[1,2147483647] with cross-validation rules |

#### group.consumer.min.session.timeout.ms <a href="#groupconsumerminsessiontimeoutms" id="groupconsumerminsessiontimeoutms"></a>

Lower bound for modern-group session timeout.

| Type:         | int                                         |
| ------------- | ------------------------------------------- |
| Default:      | 45000                                       |
| Valid Values: | \[1,2147483647] with cross-validation rules |

#### group.consumer.session.timeout.ms <a href="#groupconsumersessiontimeoutms" id="groupconsumersessiontimeoutms"></a>

Session timeout for modern (KIP-848) consumer groups.

| Type:         | int                                         |
| ------------- | ------------------------------------------- |
| Default:      | 45000                                       |
| Valid Values: | \[1,2147483647] with cross-validation rules |

#### log.retention.hours <a href="#logretentionhours" id="logretentionhours"></a>

Same setting as `log.retention.ms`, but expressed in hours.

| Type:         | long       |
| ------------- | ---------- |
| Default:      | 24 (1 day) |
| Valid Values: | \[-1,...]  |

#### log.retention.minutes <a href="#logretentionminutes" id="logretentionminutes"></a>

Same setting as `log.retention.ms`, but expressed in minutes.

| Type:         | long         |
| ------------- | ------------ |
| Default:      | 1440 (1 day) |
| Valid Values: | \[-1,...]    |

#### log.retention.ms <a href="#logretentionms" id="logretentionms"></a>

Default retention for topics, in milliseconds.

If set to a negative value, WarpStream treats retention as effectively infinite. If set to a positive value lower than 1 minute, WarpStream raises it to 1 minute.

| Type:         | long                    |
| ------------- | ----------------------- |
| Default:      | 86400000 (1 day)        |
| Valid Values: | \[-1,...,3153600000000] |

#### message.max.bytes <a href="#messagemaxbytes" id="messagemaxbytes"></a>

Cluster-level record size cap.

If this value is not explicitly set, WarpStream may omit it from `DescribeConfigs`, because the effective default depends on agent-side limits.

| Type:         | int                                             |
| ------------- | ----------------------------------------------- |
| Default:      | agent-dependent (unset at cluster config layer) |
| Valid Values: | \[0,...]                                        |

#### num.partitions <a href="#numpartitions" id="numpartitions"></a>

Default partition count used when topics are auto-created.

| Type:         | int              |
| ------------- | ---------------- |
| Default:      | 1                |
| Valid Values: | \[0, 4294967295] |

#### offsets.retention.minutes <a href="#offsetsretentionminutes" id="offsetsretentionminutes"></a>

Retention for committed consumer group offsets.

| Type:         | long           |
| ------------- | -------------- |
| Default:      | 10080 (7 days) |
| Valid Values: | \[1,...]       |

#### warpstream.default.partitions\_auto\_scaler.enabled <a href="#warpstreamdefaultpartitions_auto_scalerenabled" id="warpstreamdefaultpartitions_auto_scalerenabled"></a>

Cluster-level default for topic config `warpstream.partitions_auto_scaler.enabled`.

This default is applied to newly created topics (including auto-created topics). If a topic explicitly sets `warpstream.partitions_auto_scaler.enabled`, the topic value takes precedence.

| Type:         | string (boolean) |
| ------------- | ---------------- |
| Default:      | false            |
| Valid Values: | \[true, false]   |

#### warpstream.default.partitions\_auto\_scaler.max\_partition\_count <a href="#warpstreamdefaultpartitions_auto_scalermax_partition_count" id="warpstreamdefaultpartitions_auto_scalermax_partition_count"></a>

Cluster-level default for topic config `warpstream.partitions_auto_scaler.max_partition_count`.

This default is applied to newly created topics. A value of 0 means unlimited. If a topic explicitly sets `warpstream.partitions_auto_scaler.max_partition_count`, the topic value takes precedence.

| Type:         | long          |
| ------------- | ------------- |
| Default:      | 0 (unlimited) |
| Valid Values: | \[0,...]      |

#### warpstream.default.partitions\_auto\_scaler.partition\_count\_multiple <a href="#warpstreamdefaultpartitions_auto_scalerpartition_count_multiple" id="warpstreamdefaultpartitions_auto_scalerpartition_count_multiple"></a>

Cluster-level default for topic config `warpstream.partitions_auto_scaler.partition_count_multiple`.

This default is applied to newly created topics. A value of 0 or 1 disables the constraint. If a topic explicitly sets `warpstream.partitions_auto_scaler.partition_count_multiple`, the topic value takes precedence.

| Type:         | long     |
| ------------- | -------- |
| Default:      | 0        |
| Valid Values: | \[0,...] |

#### warpstream.default.partitions\_auto\_scaler.per\_partition\_throughput\_uncompressed\_bytes\_per\_second <a href="#warpstreamdefaultpartitions_auto_scalerper_partition_throughput_uncompressed_bytes_per_second" id="warpstreamdefaultpartitions_auto_scalerper_partition_throughput_uncompressed_bytes_per_second"></a>

Cluster-level default for topic config `warpstream.partitions_auto_scaler.per_partition_throughput_uncompressed_bytes_per_second`.

This default is applied to newly created topics. If a topic explicitly sets `warpstream.partitions_auto_scaler.per_partition_throughput_uncompressed_bytes_per_second`, the topic value takes precedence.

| Type:         | long     |
| ------------- | -------- |
| Default:      | 2500000  |
| Valid Values: | \[0,...] |

#### warpstream.default.topic.type <a href="#warpstreamdefaulttopictype" id="warpstreamdefaulttopictype"></a>

Default topic type for newly created topics.

| Type:         | string                |
| ------------- | --------------------- |
| Default:      | classic               |
| Valid Values: | \[classic, lightning] |

#### warpstream.soft.delete.topic.enable <a href="#warpstreamsoftdeletetopicenable" id="warpstreamsoftdeletetopicenable"></a>

Whether soft-delete behavior is enabled for inactive topics.

| Type:         | string (boolean) |
| ------------- | ---------------- |
| Default:      | true             |
| Valid Values: | \[true, false]   |

#### warpstream.soft.delete.topic.ttl.hours <a href="#warpstreamsoftdeletetopicttlhours" id="warpstreamsoftdeletetopicttlhours"></a>

Inactive topic TTL in hours when soft-delete is enabled.

If set to a negative value, WarpStream treats TTL as effectively infinite.

| Type:         | long       |
| ------------- | ---------- |
| Default:      | 24 (1 day) |
| Valid Values: | \[-1,...]  |

#### group.consumer.\* cross-validation rules <a href="#groupconsumer-cross-validation-rules" id="groupconsumer-cross-validation-rules"></a>

WarpStream enforces the following invariants for KIP-848 timing configs:

* `group.consumer.max.heartbeat.interval.ms >= group.consumer.min.heartbeat.interval.ms`
* `group.consumer.heartbeat.interval.ms` must be within `[min.heartbeat, max.heartbeat]`
* `group.consumer.max.session.timeout.ms >= group.consumer.min.session.timeout.ms`
* `group.consumer.session.timeout.ms` must be within `[min.session, max.session]`
* `group.consumer.heartbeat.interval.ms < group.consumer.session.timeout.ms`

#### Alter behavior <a href="#alter-behavior" id="alter-behavior"></a>

`AlterConfigs` uses classic replace semantics for known broker configs:

* keys present in request are set
* known keys omitted from request are reset/unset

`IncrementalAlterConfigs` supports:

* `SET`
* `DELETE`

`APPEND` and `SUBTRACT` are not supported for broker configs.

#### Unknown config behavior <a href="#unknown-config-behavior" id="unknown-config-behavior"></a>

* Unknown keys containing `warpstream` are rejected with `INVALID_CONFIG`.
* Unknown non-WarpStream keys are ignored for compatibility.

#### Kafka compatibility values returned by DescribeConfigs <a href="#kafka-compatibility-values-returned-by-describeconfigs" id="kafka-compatibility-values-returned-by-describeconfigs"></a>

WarpStream also reports a set of read-only Kafka-style broker config values for compatibility:

| Config key                     | Value      |
| ------------------------------ | ---------- |
| compression.type               | lz4        |
| log.flush.interval.messages    | 1          |
| log.retention.bytes            | -1         |
| unclean.leader.election.enable | false      |
| broker.id.generation.enable    | true       |
| default.replication.factor     | 3          |
| reserved.broker.max.id         | 2147483647 |

#### CLI examples <a href="#kafka-compatibility-values-returned-by-describeconfigs" id="kafka-compatibility-values-returned-by-describeconfigs"></a>

Using WarpStream CLI commands:

```bash
warpstream cli describe-broker-configs \
	-bootstrap-host localhost \
	-bootstrap-port 9092
```

```bash
warpstream cli alter-broker-config \
	-bootstrap-host localhost \
	-bootstrap-port 9092 \
	--add-config "warpstream.default.topic.type=lightning"
```

<br>