apache/kafka · error · UnsupportedOperationException

clientInstanceId not set

Error message

clientInstanceId not set

What it means

Thrown by MockProducer.clientInstanceId(Duration) as UnsupportedOperationException when telemetry is enabled but no client instance id has been configured. The mock does not generate a telemetry clientInstanceId on its own (unlike the real producer which obtains one via the InitProducerId/telemetry handshake); the test must supply one via setClientInstanceId(Uuid). It surfaces an unconfigured-telemetry call deterministically rather than letting the test proceed with null.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/producer/MockProducer.java:441

        this.injectTimeoutExceptionCounter = injectTimeoutExceptionCounter;
    }

    /**
     * Sets the client instance ID for this mock producer.
     *
     * @param instanceId The client instance ID to set
     */
    public void setClientInstanceId(final Uuid instanceId) {
        clientInstanceId = instanceId;
    }

    @Override
    public Uuid clientInstanceId(Duration timeout) {
        if (telemetryDisabled) {
            throw new IllegalStateException();
        }
        if (clientInstanceId == null) {
            throw new UnsupportedOperationException("clientInstanceId not set");
        }
        if (injectTimeoutExceptionCounter != 0) {
            // -1 is used as "infinite"
            if (injectTimeoutExceptionCounter > 0) {
                --injectTimeoutExceptionCounter;
            }
            throw new TimeoutException("TimeoutExceptions are successfully injected for test.");
        }

        return clientInstanceId;
    }

    public Map<MetricName, Metric> metrics() {
        return mockMetrics;
    }

    /**
     * Set a mock metric for testing purpose

View on GitHub (pinned to c31c9215e1)

Solutions

1. Call producer.setClientInstanceId(Uuid.randomUuid()) (or a fixed Uuid) before exercising code that calls clientInstanceId().
2. If the test does not care about telemetry, call producer.disableTelemetry() to short-circuit the method (it throws a bare IllegalStateException instead, signalling telemetry is off).
3. If testing the not-set path itself, assert UnsupportedOperationException is thrown and do not seed the id.
4. Update the production wrapper under test to tolerate an unset client instance id (e.g. treat telemetry as optional) if that matches the intended contract.

Example fix

// before
MockProducer<String,String> p = new MockProducer<>();
p.clientInstanceId(Duration.ofSeconds(1)); // UnsupportedOperationException

// after
MockProducer<String,String> p = new MockProducer<>();
p.setClientInstanceId(Uuid.randomUuid());
p.clientInstanceId(Duration.ofSeconds(1));

// Set the client instance id before requesting it, or skip telemetry.
producer.setClientInstanceId(Uuid.randomUuid());
// or, if you never want telemetry: producer.disableClientId(); // via the
// telemetryDisabled flag, set through the constructor option.

// Guard:
Uuid callClientInstanceId(MockProducer<?,?> p, Duration timeout) {
    if (p.clientInstanceId(timeout) == null) { // only safe if you've stored it
        throw new IllegalStateException("clientInstanceId not configured");
    }
    return p.clientInstanceId(timeout);
}

When it happens

Trigger: Calling producer.clientInstanceId(timeout) without first calling setClientInstanceId(Uuid) and while telemetry is not disabled (disableTelemetry() not called). The throw site is line 441, reached only if telemetryDisabled is false and clientInstanceId is null.

Common situations: A test for the telemetry/subscription code path that forgot to seed the client instance id; code under test newly calling clientInstanceId() after a version upgrade that introduced telemetry; a test that expected auto-initialization mirroring the real producer but used the mock, which has no broker handshake.

Related errors

• MockProducer is already closed.
• MockProducer is fenced.
• MockProducer hasn't been initialized for transactions.
• There is no open transaction.
• TimeoutExceptions are successfully injected for test.

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