apache/kafka · error · java.lang.IllegalStateException

Telemetry is not enabled. Set config `enable.metrics.push` t

Error message

Telemetry is not enabled. Set config `enable.metrics.push` to `true`.

What it means

IllegalStateException from clientInstanceId(Duration) when the consumer was built without a ClientTelemetryReporter, i.e. enable.metrics.push=false (the default in many setups). clientInstanceId is meant to expose the broker-assigned client instance id used for the metrics-push pipeline; without telemetry enabled there is no reporter and therefore no instance id. The message explicitly points at ConsumerConfig.ENABLE_METRICS_PUSH_CONFIG as the fix.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/internals/AsyncKafkaConsumer.java:1855

            lastPendingAsyncCommit.whenComplete((v, t) -> futureToAwait.complete(null));
            if (enableWakeup) {
                wakeupTrigger.setActiveTask(futureToAwait);
            }
            ConsumerUtils.getResult(futureToAwait, timer);
            lastPendingAsyncCommit = null;
        } finally {
            if (enableWakeup) {
                wakeupTrigger.clearTask();
            }
            timer.update();
        }
        offsetCommitCallbackInvoker.executeCallbacks();
    }

    @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 Set<TopicPartition> assignment() {
        acquireAndEnsureOpen();
        try {
            return Collections.unmodifiableSet(subscriptions.assignedPartitions());
        } finally {
            release();
        }
    }

    /**
     * Get the current subscription, or an empty set if no such call has
     * been made.

View on GitHub (pinned to c31c9215e1)

Solutions

Set ConsumerConfig.ENABLE_METRICS_PUSH_CONFIG=true in the consumer properties before construction; the reporter is wired only at construction time.
Reconstruct the consumer after changing the config (toggling the flag post-construction has no effect).
Verify the broker actually supports the telemetry subscription API if you depend on the instance id downstream.

Example fix

// before
props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, brokers);
consumer = new AsyncKafkaConsumer<>(props, k, v);
uuid = consumer.clientInstanceId(Duration.ofSeconds(5)); // throws

// after
props.put(ConsumerConfig.ENABLE_METRICS_PUSH_CONFIG, "true");
consumer = new AsyncKafkaConsumer<>(props, k, v);
uuid = consumer.clientInstanceId(Duration.ofSeconds(5));

Defensive patterns

Strategy: validation

Validate before calling

boolean telemetryEnabled = Boolean.parseBoolean(
    props.getProperty(ConsumerConfig.ENABLE_METRICS_PUSH_CONFIG, "false"));
if (!telemetryEnabled) {
    throw new IllegalStateException(
        "Cannot call clientInstanceId() without " + ConsumerConfig.ENABLE_METRICS_PUSH_CONFIG + "=true");
}
new KafkaConsumer<K, V>(props);

Try / catch

try {
    Uuid id = consumer.clientInstanceId(timeout);
} catch (IllegalStateException e) {
    // Telemetry not enabled at construction; nothing to retry — fix config and rebuild consumer.
    log.warn("clientInstanceId unavailable: enable.metrics.push is disabled", e);
}

Prevention

clientInstanceId() requires ConsumerConfig.ENABLE_METRICS_PUSH_CONFIG=true at consumer construction — toggling it later has no effect.
Gate any telemetry/observability feature on a config check before calling clientInstanceId.
Treat IllegalStateException here as a permanent misconfiguration, not a transient condition.

When it happens

Trigger: Calling consumer.clientInstanceId(timeout) on a consumer whose properties did not include enable.metrics.push=true. The optional clientTelemetryReporter field is empty, so the guard throws immediately before any network interaction.

Common situations: Integration with observability/telemetry collectors (e.g. client metrics to a broker-backed dashboard) where the application expects a clientInstanceId but the consumer config was copied from a non-telemetry template; upgrading the broker and wanting clientInstanceId correlation without flipping the metrics push flag; multi-tenant clients where some instances opt in and some do not.

Related errors

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