> For the complete documentation index, see [llms.txt](https://docs.warpstream.com/warpstream/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.warpstream.com/warpstream/kafka/reference/protocol-and-feature-support/broker-configuration-reference.md).

# 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.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 \
	-config-name warpstream.default.topic.type \
	-config-value lightning
```

<br>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.warpstream.com/warpstream/kafka/reference/protocol-and-feature-support/broker-configuration-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.