# Limits & Rules (/connectors/kafka/reference/limits-and-rules)



Two kinds of limit apply to the connector: **hard limits** (fixed in code, not configurable —
protecting the wire protocol and the channel-injectivity guarantees `reference/topic-mapping`
depends on) and **operator-configurable caps** (the `CONNECTORS_KAFKA_*` settings that bound
per-topic, per-request, and per-connection resource use). Both are listed here; the full
field-by-field settings reference — including fields not covered by this page, like transaction
timeouts and byte-rate quotas — lives at
[Configuration reference](/configure/reference/connectors#kafka).

## Hard limits (not configurable) [#hard-limits-not-configurable]

| Rule                   | Value                                               | Enforced at                         |
| ---------------------- | --------------------------------------------------- | ----------------------------------- |
| Partitions per topic   | **256**, hard cap, **increase-only**                | `CreateTopics` / `CreatePartitions` |
| Message timestamp type | **`CreateTime` only** — `LogAppendTime` is rejected | Server startup (config validation)  |

A violation of either rule is a config-time or admin-time rejection, never a silent clamp — see
[Notes on the trickier ones](#notes-on-the-trickier-ones) below.

## Operator-configurable caps (`CONNECTORS_KAFKA_*`) [#operator-configurable-caps-connectors_kafka_]

Server-side settings in `[Connectors.Kafka]`; env vars use the `CONNECTORS_KAFKA_*` prefix.
Defaults and ceilings below are the connector's own floor/ceiling pair — an unset or non-positive
value falls back to the default (there is no "unbounded" mode on any of these), and a value above
the ceiling is rejected at server startup.

| Field                     | Env var                                       | Default           | Ceiling                | What happens over the limit                                                                                                                                                                                                             |
| ------------------------- | --------------------------------------------- | ----------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MaxMessageBytes`         | `CONNECTORS_KAFKA_MAX_MESSAGE_BYTES`          | `1048576` (1 MiB) | `1073741824` (1 GiB)   | An over-size `Produce` record is rejected `MESSAGE_TOO_LARGE` — no `Append` is attempted                                                                                                                                                |
| `MaxConnections`          | `CONNECTORS_KAFKA_MAX_CONNECTIONS`            | `1000`            | none (`0` = unlimited) | A new TCP connection at or over the cap is refused at accept — Kafka has no `CONNECT` frame to carry a wire-level error, so the client simply cannot connect                                                                            |
| `MaxGroups`               | `CONNECTORS_KAFKA_MAX_GROUPS`                 | `10000`           | `10000000`             | An unseen group name over the cap is refused the retriable `COORDINATOR_NOT_AVAILABLE` at `JoinGroup`/`OffsetCommit`                                                                                                                    |
| `MaxTopicsPerRequest`     | `CONNECTORS_KAFKA_MAX_TOPICS_PER_REQUEST`     | `10000`           | `1000000`              | An over-cap request closes the connection outright — a bounded, O(1) reject, never a per-topic-shaped response, enforced before authorization on `Produce`/`Fetch`/`ListOffsets`/`OffsetForLeaderEpoch`/`Metadata`/the admin topic APIs |
| `MaxPartitionsPerRequest` | `CONNECTORS_KAFKA_MAX_PARTITIONS_PER_REQUEST` | `100000`          | `10000000`             | Same as `MaxTopicsPerRequest` — the connection is closed, not answered                                                                                                                                                                  |
| `OffsetsRetentionMinutes` | `CONNECTORS_KAFKA_OFFSETS_RETENTION_MINUTES`  | `10080` (7 days)  | `52560000` (100 years) | A committed consumer-group offset older than this is expired by the group reaper on its next sweep — not an error, a retention rule                                                                                                     |
| `ScramIterations`         | `CONNECTORS_KAFKA_SCRAM_ITERATIONS`           | `4096`            | `1000000`              | Applies only at server boot (SCRAM verifier derivation) — an out-of-range value fails startup with a configuration error, not a runtime request                                                                                         |

<Callout type="warn">
  **Fan-out caps are authorization-independent.** `MaxTopicsPerRequest` and
  `MaxPartitionsPerRequest` are enforced at the dispatch layer *before* the authorization check and
  the handler — the cap holds even with authorization disabled, since a pre-auth flood of distinct
  topic or partition names in one frame is exactly the fan-out this guards against.
</Callout>

## Notes on the trickier ones [#notes-on-the-trickier-ones]

* **256 partitions is a hard ceiling with no override.** `CreateTopics` with `NumPartitions > 256`
  is rejected `INVALID_PARTITIONS`. `CreatePartitions` follows the same rule for growth: `Count`
  must strictly exceed the topic's current partition count — a same-count or lower `Count` is
  also rejected `INVALID_PARTITIONS` (never shrink, never no-op), and a `Count` above 256 is
  rejected the same way. A partition increase, once accepted, is durable and cannot be reversed.
  See [Partitions & Ordering](/connectors/kafka/concepts/partitions-and-ordering) for the
  ordering consequences of growing partition count on an existing topic.
* **`MaxMessageBytes`'s 1 GiB ceiling is a safety bound, not a recommendation.** Kafka frames are
  length-prefixed by a 32-bit integer; the ceiling keeps `MaxMessageBytes` comfortably below the
  point where the frame-length arithmetic could wrap. Most deployments should raise the 1 MiB
  default modestly (a few MiB) rather than approach the ceiling.
* **Per-topic `max.message.bytes` is echo-only.** `DescribeConfigs` and
  `IncrementalAlterConfigs` accept and reflect a topic-level `max.message.bytes` override, but
  enforcement always uses the broker-wide `MaxMessageBytes` above (default 1 MiB, operator-raisable
  up to the 1 GiB ceiling) — a topic config can never raise the enforced limit.
* **`MaxConnections` fails closed at the TCP layer, not the Kafka protocol layer.** Because Kafka
  has no in-band "too many connections" response, a client at the cap sees a plain connection
  refusal — indistinguishable, on the wire, from the port being closed. Size `MaxConnections` for
  your real client fleet (each consumer, producer, and admin tool holds at least one connection)
  before relying on it as a guardrail.
* **`OffsetsRetentionMinutes` is a retention rule, not a request-time limit.** Unlike the other
  rows, exceeding it produces no error at all — a consumer group's committed offset simply ages out
  and is treated as absent (falls back to `auto.offset.reset`) the next time that group is
  described or resumes.
* **`ScramIterations` only matters if you run SASL/SCRAM.** It is read once, at connector
  construction, to derive each configured user's SCRAM verifier — raising it strengthens
  brute-force resistance at a one-time boot cost, never a per-authentication cost.

## Related [#related]

<Cards>
  <Card title="Error Codes" href="/connectors/kafka/reference/error-codes" description="Every Kafka protocol error code the connector returns, including MESSAGE_TOO_LARGE and INVALID_PARTITIONS." />

  <Card title="Capabilities" href="/connectors/kafka/reference/capabilities" description="The full supported Kafka API surface these limits govern, including version ranges and preview features." />

  <Card title="Topic Mapping" href="/connectors/kafka/reference/topic-mapping" description="How the 256-partition cap and offset semantics connect to the underlying channel grammar." />

  <Card title="Configuration reference" href="/configure/reference/connectors#kafka" description="The complete Connectors.Kafka.* settings, ports, and TLS/SASL options." />
</Cards>