{"id":"a3b25659b1a8ea99","repo":"apache/kafka","slug":"telemetry-is-not-enabled-set-config-to-true","errorCode":null,"errorMessage":"Telemetry is not enabled. Set config `{}` to `true`.","messagePattern":"Telemetry is not enabled\\. Set config `(.+?)` to `true`\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/consumer/internals/ClassicKafkaConsumer.java","lineNumber":926,"sourceCode":"            offsets = coordinator.fetchCommittedOffsets(partitions, time.timer(timeout));\n            if (offsets == null) {\n                throw new TimeoutException(\"Timeout of \" + timeout.toMillis() + \"ms expired before the last \" +\n                        \"committed offset for partitions \" + partitions + \" could be determined. Try tuning \" +\n                        ConsumerConfig.DEFAULT_API_TIMEOUT_MS_CONFIG + \" larger to relax the threshold.\");\n            } else {\n                offsets.forEach(this::updateLastSeenEpochIfNewer);\n                return offsets;\n            }\n        } finally {\n            kafkaConsumerMetrics.recordCommitted(time.nanoseconds() - start);\n            release();\n        }\n    }\n\n    @Override\n    public Uuid clientInstanceId(Duration timeout) {\n        if (clientTelemetryReporter.isEmpty()) {\n            throw new IllegalStateException(\"Telemetry is not enabled. Set config `\" + ConsumerConfig.ENABLE_METRICS_PUSH_CONFIG + \"` to `true`.\");\n\n        }\n\n        return ClientTelemetryUtils.fetchClientInstanceId(clientTelemetryReporter.get(), timeout);\n    }\n\n    @Override\n    public Map<MetricName, ? extends Metric> metrics() {\n        return Collections.unmodifiableMap(this.metrics.metrics());\n    }\n\n    @Override\n    public List<PartitionInfo> partitionsFor(String topic) {\n        return partitionsFor(topic, Duration.ofMillis(defaultApiTimeoutMs));\n    }\n\n    @Override\n    public List<PartitionInfo> partitionsFor(String topic, Duration timeout) {","sourceCodeStart":908,"sourceCodeEnd":944,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/consumer/internals/ClassicKafkaConsumer.java#L908-L944","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nUuid id = consumer.clientInstanceId(Duration.ofSeconds(5));\n\n// after\nprops.put(ConsumerConfig.ENABLE_METRICS_PUSH_CONFIG, \"true\");\nKafkaConsumer<String,String> consumer = new KafkaConsumer<>(props);\nUuid id = consumer.clientInstanceId(Duration.ofSeconds(5));","handlingStrategy":"validation","validationCode":"// Check the same config key you would set to enable telemetry:\nboolean telemetryOn = Boolean.parseBoolean(\n    props.getProperty(ConsumerConfig.ENABLE_METRICS_PUSH_CONFIG, \"false\"));\nif (!telemetryOn) {\n    throw new IllegalStateException(\n        \"clientInstanceId() requires \" + ConsumerConfig.ENABLE_METRICS_PUSH_CONFIG + \"=true\");\n}\nreturn consumer.clientInstanceId(Duration.ofSeconds(10));","typeGuard":"// Wrap the consumer so the type itself reflects telemetry state:\nfinal class TelemetryEnabledConsumer<K,V> {\n    private final KafkaConsumer<K,V> delegate;\n    TelemetryEnabledConsumer(Map<String,Object> cfg) {\n        if (!Boolean.TRUE.equals(cfg.get(ConsumerConfig.ENABLE_METRICS_PUSH_CONFIG)))\n            throw new IllegalArgumentException(\"enable.metrics.push must be true\");\n        delegate = new KafkaConsumer<>(cfg);\n    }\n    Uuid clientInstanceId(Duration t) { return delegate.clientInstanceId(t); }\n}","tryCatchPattern":"// Treat telemetry as optional: degrade gracefully instead of crashing the app:\ntry {\n    return consumer.clientInstanceId(Duration.ofSeconds(10));\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"Telemetry is not enabled\")) {\n        log.debug(\"Telemetry disabled; skipping clientInstanceId\");\n        return null;\n    }\n    throw e;\n}","preventionTips":["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."],"tags":["consumer","telemetry","config","java"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}