apache/kafka · error · ConfigException

entry must be non null

Error message

entry must be non null

What it means

Thrown by NonNullValidator.ensureValid when the validated value is null. NonNullValidator is the simplest Validator implementation: it permits any non-null value (no type or content checks) and rejects only null. The literal string "null" is passed as the value argument to ConfigException to satisfy spotbugs/nullable-analysis, so the exception's getValue() reports "null" rather than a null reference.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/config/ConfigDef.java:1158

        @Override
        public void ensureValid(String name, Object o) {
            String s = (String) o;
            if (s == null || !validStrings.contains(s.toUpperCase(Locale.ROOT))) {
                throw new ConfigException(name, o, "String must be one of (case insensitive): " + String.join(", ", validStrings));
            }
        }

        public String toString() {
            return "(case insensitive) [" + String.join(", ", validStrings) + "]";
        }
    }

    public static class NonNullValidator implements Validator {
        @Override
        public void ensureValid(String name, Object value) {
            if (value == null) {
                // Pass in the string null to avoid the spotbugs warning
                throw new ConfigException(name, "null", "entry must be non null");
            }
        }

        public String toString() {
            return "non-null string";
        }
    }

    public static class LambdaValidator implements Validator {
        BiConsumer<String, Object> ensureValid;
        Supplier<String> toStringFunction;

        private LambdaValidator(BiConsumer<String, Object> ensureValid,
                                Supplier<String> toStringFunction) {
            this.ensureValid = ensureValid;
            this.toStringFunction = toStringFunction;
        }

View on GitHub (pinned to c31c9215e1)

Solutions

1. Set the named config to any non-null value in your Properties/Map.
2. If the config is genuinely optional, give the ConfigKey a sensible default via ConfigDef.define(..., defaultValue, ...).
3. Audit env-var/secret-injection pipelines (e.g. Kubernetes secretKeyRef) to confirm the source actually produced a value.

Example fix

// before
// client.id omitted entirely
props.put("bootstrap.servers", "localhost:9092");

// after
props.put("bootstrap.servers", "localhost:9092");
props.put("client.id", "order-service-producer");

// Reject null at the boundary for keys known to use NonNullValidator (e.g. client.id, transactional.id):
for (String nonNullKey : Set.of("client.id", "transactional.id")) {
    if (configs.containsKey(nonNullKey) && configs.get(nonNullKey) == null) {
        throw new IllegalArgumentException(nonNullKey + " must not be null");
    }
}

// Use Java's Optional or @NonNull annotation to make null impossible in your config wrapper:
record KafkaConfig(@NonNull String clientId, @NonNull String bootstrapServers) {}
// then map fields -> Properties, never exposing null.

try {
    new KafkaProducer<>(props);
} catch (ConfigException ce) {
    if (ce.getMessage().contains("entry must be non null")) {
        log.error("Required kafka config '{}' was null", ce.getName());
        failStartup();
    } else throw ce;
}

When it happens

Trigger: A ConfigKey registered with .validator(new NonNullValidator()) (or equivalent) is parsed and the properties Map has no entry for that key and the ConfigKey has no default, or the key is explicitly mapped to null. Triggered during ConfigDef.parse() within the validator loop.

Common situations: Required identifier configs (client.id, transactional.id, group.instance.id, or module-specific required strings) left unset in properties files. Common when a config was previously optional with a default and a version bump made a default absent, or when env-var templating fails to substitute.

Related errors

• Configuration 'name' values must not be null.
• Configuration 'name' must not be empty. Valid values include
• Configuration 'name' values must not be duplicated.
• Configuration 'name' values must not be empty.
• String must be one of: String.join(", ", validStrings)

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