apache/kafka · error · ConfigException

client.rack must be provided if partitioner.rack.aware is en

Error message

client.rack must be provided if partitioner.rack.aware is enabled

What it means

Thrown by RecordAccumulator.PartitionerConfig's constructor when partitioner.rack.aware=true but the producer's client.rack is null or blank. Rack-aware partitioning requires a producer rack so the built-in partitioner can prefer a leader replica in the same rack; without one the constraint cannot be honoured, so construction fails fast at producer init rather than silently degrading.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/producer/internals/RecordAccumulator.java:1283

        /**
         * Partitioner config
         *
         * @param enableAdaptivePartitioning If it's true, partition switching adapts to broker load, otherwise partition
         *        switching is random.
         * @param partitionAvailabilityTimeoutMs If a broker cannot process produce requests from a partition
         *        for the specified time, the partition is treated by the partitioner as not available.
         *        If the timeout is 0, this logic is disabled.
         * @param rackAware Whether the built-in partitioner is configured to be rack-aware.
         * @param rack The producer rack.
         */
        public PartitionerConfig(boolean enableAdaptivePartitioning, long partitionAvailabilityTimeoutMs, boolean rackAware, String rack) {
            this.enableAdaptivePartitioning = enableAdaptivePartitioning;
            this.partitionAvailabilityTimeoutMs = partitionAvailabilityTimeoutMs;
            this.rackAware = rackAware;
            this.rack = rack;

            if (rackAware && Utils.isBlank(rack)) {
                throw new ConfigException("client.rack must be provided if partitioner.rack.aware is enabled");
            }
        }

        public PartitionerConfig() {
            this(false, 0, false, "");
        }
    }

    /*
     * Result of an attempt to append a record to the accumulator. Carries exactly one of three
     * mutually-exclusive outcomes: the record was appended ({@link RecordAppendResult#appended()}, {@code future} is set),
     * the open batch needs more chunk capacity first ({@link RecordAppendResult#needsBufferExtension()}),
     * or a new batch must be created for the record ({@link RecordAppendResult#needsNewBatch()}).
     */
    public static final class RecordAppendResult {
        /**
         * The three mutually-exclusive outcomes of an append attempt. Internal representation only;
         * callers use {@link #appended()}, {@link #needsBufferExtension()}, and {@link #needsNewBatch()}.

View on GitHub (pinned to c31c9215e1)

Solutions

1. Set client.rack to a non-blank value (typically the AZ/zone, e.g. "us-east-1a") whenever partitioner.rack.aware=true.
2. Or, if rack-awareness is not actually wanted, set partitioner.rack.aware=false (the default).
3. Drive client.rack from the deployment environment (e.g. AWS availability-zone via instance metadata) so it is never blank.
4. Validate required config pairs at application startup so the failure is logged with context before the producer is constructed.

Example fix

// before
props.put("partitioner.rack.aware", "true");
// client.rack omitted -> ConfigException

// after
props.put("partitioner.rack.aware", "true");
props.put("client.rack", System.getenv("AZ")); // e.g. "us-east-1a"

String rack = configs.get("client.rack") == null ? null : String.valueOf(configs.get("client.rack")).trim();
boolean rackAware = Boolean.parseBoolean(String.valueOf(configs.getOrDefault("partitioner.rack.aware", "false")));
if (rackAware && rack == null || rack != null && rack.isEmpty()) {
    throw new IllegalArgumentException("client.rack must be set when partitioner.rack.aware=true");
}

try {
    producer = new KafkaProducer<>(configs);
} catch (org.apache.kafka.common.config.ConfigException ce) {
    // log, abort startup, and fix configuration before retrying
}

When it happens

Trigger: Configuring partitioner.rack.aware=true (or partitioner.class that delegates rack-aware behaviour to the built-in) without also setting client.rack. The ConfigException is raised during KafkaProducer construction when the PartitionerConfig is built.

Common situations: Copied config from a broker or another client that had client.rack set; deployment into a new region/AZ where client.rack was not templated; enable rack-awareness for cross-AZ bandwidth savings but forget the matching client.rack; environment-variable-driven config where CLIENT_RACK was unset.

Related errors

• Transactional method invoked on a non-transactional producer
• Telemetry is not enabled. Set config `{}` to `true`.
• Tried to force a rebalance but consumer does not have a grou
• The timeout cannot be negative.
• The ${ProducerConfig.BUFFER_MEMORY_ALLOCATION_STRATEGY_INCRE

AI-assisted analysis of apache/kafka@c31c9215e1 (2026-08-03). Data as JSON: /data/errors/e11ee3798e3c1202.json. Report an issue: GitHub.