apache/kafka · error · UnsupportedOperationException

clientInstanceId not set

Error message

clientInstanceId not set

What it means

Thrown by MockConsumer.clientInstanceId(Duration) when clientInstanceId was never set via setClientInstanceId(Uuid) and telemetry is not disabled. The mock does not auto-generate an instance id (unlike the real consumer); tests that exercise telemetry must explicitly inject one, or disable telemetry, otherwise the call is unsupported.

Solutions

1. Call mock.setClientInstanceId(Uuid.randomUuid()) before exercising clientInstanceId().
2. If the test does not cover telemetry, call mock.setTelemetryDisabled(true) to short-circuit the path.
3. Guard production telemetry code behind a feature flag so mocks that lack an instance id do not invoke it.

Example fix

// before
MockConsumer<String,String> mock = new MockConsumer<>(OffsetResetStrategy.EARLIEST);
Uuid id = mock.clientInstanceId(Duration.ofSeconds(5)); // throws

// after
mock.setClientInstanceId(Uuid.MIGRATED_CLIENT_INSTANCE_ID); // or Uuid.randomUuid()
Uuid id = mock.clientInstanceId(Duration.ofSeconds(5));

if (mockClientInstanceId == null) {
    // either inject one or disable telemetry for this test
    mockConsumer.setTelemetryDisabled(true);
}
Uuid id = mockConsumer.clientInstanceId(Duration.ofSeconds(5));

static boolean mockHasInstanceId(MockConsumer<?,?> m) {
    try { m.clientInstanceId(Duration.ZERO); return true; }
    catch (UnsupportedOperationException | IllegalStateException e) { return false; }
}

try {
    return mockConsumer.clientInstanceId(timeout);
} catch (UnsupportedOperationException e) {
    if ("clientInstanceId not set".equals(e.getMessage())) {
        return Optional.empty(); // or skip telemetry
    }
    throw e;
}

When it happens

Trigger: Calling clientInstanceId on a MockConsumer without prior setClientInstanceId; telemetry not disabled via setTelemetryDisabled(true); test code copied from the real consumer without mock setup.

Common situations: Telemetry/metrics tests using MockConsumer; framework code that calls clientInstanceId unconditionally on any Consumer; integration glue tested with mocks.

Related errors

• Not implemented yet.
• Cannot add records for a partition that is not assigned to…
• Cannot lose partitions that are not currently assigned
• MaxPollRecords must be strictly superior to 0
• MockConsumer didn't have beginning offset specified, but…

AI-assisted analysis of apache/kafka@996fb4585a (2026-08-11). Data as JSON: /api/errors/a22c53bb8acab479. Report an issue: GitHub.

Appendix: source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/MockConsumer.java:571

        this.injectTimeoutExceptionCounter = injectTimeoutExceptionCounter;
    }

    /**
     * Sets the client instance ID for this mock consumer.
     *
     * @param instanceId the client instance ID
     */
    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();
        }

        return clientInstanceId;
    }

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

View on GitHub (pinned to 996fb4585a)