What causes "Telemetry is not enabled. Set config `{}` to `true`." in apache/kafka?

Set enable.metrics.push=true in consumer properties before constructing the consumer.

apache/kafka · error · IllegalStateException

Telemetry is not enabled. Set config `{}` to `true`.

Error message

Telemetry is not enabled. Set config `{}` to `true`.

What it means

Thrown by KafkaConsumer.clientInstanceId(Duration) when client telemetry is not configured (clientTelemetryReporter is empty). The client instance id is only available when the metrics push channel is enabled via enable.metrics.push=true. Without telemetry the broker cannot assign a stable instance id, so this IllegalStateException marks the feature as off.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/internals/ClassicKafkaConsumer.java:926

            offsets = coordinator.fetchCommittedOffsets(partitions, time.timer(timeout));
            if (offsets == null) {
                throw new TimeoutException("Timeout of " + timeout.toMillis() + "ms expired before the last " +
                        "committed offset for partitions " + partitions + " could be determined. Try tuning " +
                        ConsumerConfig.DEFAULT_API_TIMEOUT_MS_CONFIG + " larger to relax the threshold.");
            } else {
                offsets.forEach(this::updateLastSeenEpochIfNewer);
                return offsets;
            }
        } finally {
            kafkaConsumerMetrics.recordCommitted(time.nanoseconds() - start);
            release();
        }
    }

    @Override
    public Uuid clientInstanceId(Duration timeout) {
        if (clientTelemetryReporter.isEmpty()) {
            throw new IllegalStateException("Telemetry is not enabled. Set config `" + ConsumerConfig.ENABLE_METRICS_PUSH_CONFIG + "` to `true`.");

        }

        return ClientTelemetryUtils.fetchClientInstanceId(clientTelemetryReporter.get(), timeout);
    }

    @Override
    public Map<MetricName, ? extends Metric> metrics() {
        return Collections.unmodifiableMap(this.metrics.metrics());
    }

    @Override
    public List<PartitionInfo> partitionsFor(String topic) {
        return partitionsFor(topic, Duration.ofMillis(defaultApiTimeoutMs));
    }

    @Override
    public List<PartitionInfo> partitionsFor(String topic, Duration timeout) {

View on GitHub (pinned to c31c9215e1)

Solutions

Set enable.metrics.push=true in consumer properties before constructing the consumer.
Verify the broker version supports client telemetry (KRaft brokers >= 3.8 / Kafka >= 4.0 with metrics support).
Guard the call: only invoke clientInstanceId when your config enables it; otherwise skip telemetry-dependent logic.

Example fix

// before
Uuid id = consumer.clientInstanceId(Duration.ofSeconds(5));

// after
props.put(ConsumerConfig.ENABLE_METRICS_PUSH_CONFIG, "true");
KafkaConsumer<String,String> consumer = new KafkaConsumer<>(props);
Uuid id = consumer.clientInstanceId(Duration.ofSeconds(5));

Defensive patterns

Strategy: validation

Validate before calling

// Check the same config key you would set to enable telemetry:
boolean telemetryOn = Boolean.parseBoolean(
    props.getProperty(ConsumerConfig.ENABLE_METRICS_PUSH_CONFIG, "false"));
if (!telemetryOn) {
    throw new IllegalStateException(
        "clientInstanceId() requires " + ConsumerConfig.ENABLE_METRICS_PUSH_CONFIG + "=true");
}
return consumer.clientInstanceId(Duration.ofSeconds(10));

Type guard

// Wrap the consumer so the type itself reflects telemetry state:
final class TelemetryEnabledConsumer<K,V> {
    private final KafkaConsumer<K,V> delegate;
    TelemetryEnabledConsumer(Map<String,Object> cfg) {
        if (!Boolean.TRUE.equals(cfg.get(ConsumerConfig.ENABLE_METRICS_PUSH_CONFIG)))
            throw new IllegalArgumentException("enable.metrics.push must be true");
        delegate = new KafkaConsumer<>(cfg);
    }
    Uuid clientInstanceId(Duration t) { return delegate.clientInstanceId(t); }
}

Try / catch

// Treat telemetry as optional: degrade gracefully instead of crashing the app:
try {
    return consumer.clientInstanceId(Duration.ofSeconds(10));
} catch (IllegalStateException e) {
    if (e.getMessage().contains("Telemetry is not enabled")) {
        log.debug("Telemetry disabled; skipping clientInstanceId");
        return null;
    }
    throw e;
}

Prevention

Centralize consumer config in one factory; set enable.metrics.push=true there so every consumer instance is consistent.
Treat clientInstanceId() as best-effort telemetry plumbing, not a load-bearing call — never let its failure break your consume loop.
Document which deployment profiles have telemetry on; this misconfig is almost always environment drift.

When it happens

Trigger: Calling consumer.clientInstanceId(...) without setting enable.metrics.push=true in the consumer config; calling it on a consumer constructed before telemetry support or with the property explicitly false.

Common situations: Adopting KIP-714 client metrics push and forgetting the config; library code that assumes telemetry is on by default; integration with observability tooling that expects a client instance id.

Related errors

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