apache/kafka · error · IllegalStateException

Telemetry is not enabled. Set config `${ConsumerConfig.ENABL

Error message

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

What it means

Thrown by ShareConsumerImpl.clientInstanceId(Duration) (line 936) when clientTelemetryReporter is empty — i.e. the consumer was built without enable.metrics.push=true. clientInstanceId returns the broker-assigned client instance UUID, which only exists when the client telemetry reporter is registered and pushing metrics. The guard prevents asking for an ID that can never be obtained.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/internals/ShareConsumerImpl.java:936

                if (acknowledgementCommitCallbackHandler != null) {
                    ShareAcknowledgementCommitCallbackRegistrationEvent event = new ShareAcknowledgementCommitCallbackRegistrationEvent(false);
                    applicationEventHandler.add(event);
                }
                completedAcknowledgements.clear();
                acknowledgementCommitCallbackHandler = null;
            }
        } finally {
            release();
        }
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public Uuid clientInstanceId(final 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);
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public Optional<Integer> acquisitionLockTimeoutMs() {
        acquireAndEnsureOpen();
        try {
            return currentFetch.acquisitionLockTimeoutMs();
        } finally {
            release();
        }
    }

View on GitHub (pinned to c31c9215e1)

Solutions

Set enable.metrics.push=true in the consumer properties passed to KafkaShareConsumer.
Verify the property survives any config-merge layer (Spring Boot, Quarkus, custom ConfigProvider) by logging ConsumerConfig values at startup.
If telemetry is genuinely not wanted, stop calling clientInstanceId() — remove that code path rather than enabling the reporter just to obtain an ID.
Ensure the broker version supports the telemetry endpoint (KRaft broker with client metrics support); an empty reporter can also result from a broker that advertised no telemetry during metadata exchange.

Example fix

// before
props.put(ConsumerConfig.GROUP_ID_CONFIG, "g1");
Uuid id = consumer.clientInstanceId(Duration.ofSeconds(5));

// after
props.put(ConsumerConfig.GROUP_ID_CONFIG, "g1");
props.put(ConsumerConfig.ENABLE_METRICS_PUSH_CONFIG, "true");
Uuid id = consumer.clientInstanceId(Duration.ofSeconds(5));

Defensive patterns

Strategy: validation

Validate before calling

// Before invoking clientInstanceId(timeout), verify telemetry was enabled at construction time.
Object raw = consumerConfig.get(org.apache.kafka.clients.consumer.ConsumerConfig.ENABLE_METRICS_PUSH_CONFIG);
boolean telemetryEnabled = Boolean.parseBoolean(String.valueOf(raw));
if (!telemetryEnabled) {
    throw new IllegalStateException(
        "Cannot fetch client instance id: " + org.apache.kafka.clients.consumer.ConsumerConfig.ENABLE_METRICS_PUSH_CONFIG + " must be true");
}

Type guard

null

Try / catch

try {
    org.apache.kafka.common.Uuid id = consumer.clientInstanceId(java.time.Duration.ofSeconds(5));
} catch (IllegalStateException e) {
    // Telemetry disabled: either enable enable.metrics.push and recreate consumer, or skip the call.
    log.warn("clientInstanceId unavailable; enable {} in the consumer config",
             org.apache.kafka.clients.consumer.ConsumerConfig.ENABLE_METRICS_PUSH_CONFIG, e);
}

Prevention

Set enable.metrics.push=true in the consumer config when you intend to call clientInstanceId.
Treat clientInstanceId() as optional and guard callers so a missing telemetry reporter does not crash the app.
Avoid calling clientInstanceId() on every request; cache the result once the consumer is initialized.

When it happens

Trigger: Calling consumer.clientInstanceId(timeout) on a KafkaShareConsumer whose config did not set enable.metrics.push=true. Also reached if the property was set but overridden/removed by a parent config layer, or misspelled.

Common situations: Telemetry/KIP-714 integrations that want the client instance id for correlation but forgot the prerequisite config; copying a working consumer config into a new module and dropping the metrics-push flag; environments where a security/compliance layer strips unknown properties; upgrading the client and assuming telemetry is on by default (it defaults to false).

Related errors

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