apache/pulsar · error · IllegalArgumentException

Key is not provided

Error message

Key is not provided

What it means

Thrown by ComponentImpl.validateFunctionStateParams when the state key is missing. The key identifies the individual state entry (e.g. a counter) stored for the function, so a null key makes the state request meaningless.

Source

Thrown at pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/rest/api/ComponentImpl.java:1614

    }

    private void validateFunctionStateParams(final String tenant,
                                             final String namespace,
                                             final String functionName,
                                             final String key)
            throws IllegalArgumentException {

        if (tenant == null) {
            throw new IllegalArgumentException("Tenant is not provided");
        }
        if (namespace == null) {
            throw new IllegalArgumentException("Namespace is not provided");
        }
        if (functionName == null) {
            throw new IllegalArgumentException(ComponentTypeUtils.toString(componentType) + " name is not provided");
        }
        if (key == null) {
            throw new IllegalArgumentException("Key is not provided");
        }
    }

    private String getFunctionCodeBuiltin(FunctionDetails functionDetails,
                                          FunctionDetails.ComponentType componentType) {
        if (componentType == FunctionDetails.ComponentType.SOURCE && functionDetails.hasSource()) {
            SourceSpec sourceSpec = functionDetails.getSource();
            if (!isEmpty(sourceSpec.getBuiltin())) {
                return sourceSpec.getBuiltin();
            }
        }

        if (componentType == FunctionDetails.ComponentType.SINK && functionDetails.hasSink()) {
            SinkSpec sinkSpec = functionDetails.getSink();
            if (!isEmpty(sinkSpec.getBuiltin())) {
                return sinkSpec.getBuiltin();
            }
        }

View on GitHub (pinned to 820761864e)

Solutions

  1. Provide the state key in the call/path.
  2. Validate the key is non-null (and usually non-empty) before calling.
  3. If the key is computed, check the computation didn't return null.

Example fix

// before
worker.getFunctionState("public", "ns", "fn", null);
// after
if (key == null || key.isEmpty()) { throw new IllegalArgumentException("state key required"); }
worker.getFunctionState("public", "ns", "fn", key);
Defensive patterns

Strategy: validation

Validate before calling

if (key == null || key.isEmpty()) throw new IllegalArgumentException("state key required");

Type guard

boolean isProvided(String s) { return s != null && !s.isEmpty(); }

Try / catch

try { state = admin.functions().getFunctionState(t, ns, fn, key); }
catch (IllegalArgumentException e) { /* log missing state key */ }

Prevention

When it happens

Trigger: Calling ComponentImpl.getFunctionState or updateFunctionState with key == null; REST GET/POST to /functions/{tenant}/{namespace}/{functionName}/state/{key} with an empty key.

Common situations: Key argument dropped when calling programmatically; URL path built with an empty key segment; CLI missing --key option.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/64223b1fdc198594. Report an issue: GitHub.