apache/pulsar · error · IllegalArgumentException

Field ${name} must not be null

Error message

Field ${name} must not be null

What it means

ConfigValidationUtils.NestableFieldValidator.validateField throws IllegalArgumentException when a configuration field is null and the validator was built with notNull=true. This is the scalar-type validator: it first rejects nulls, then checks the field is an instance of the expected class.

Source

Thrown at pulsar-config-validation/src/main/java/org/apache/pulsar/config/validation/ConfigValidationUtils.java:41

/**
 * Helper methods for ConfigValidationAnnotations.
 */
public class ConfigValidationUtils {
    /**
     * Returns a new NestableFieldValidator for a given class.
     *
     * @param cls     the Class the field should be a type of
     * @param notNull whether or not a value of null is valid
     * @return a NestableFieldValidator for that class
     */
    public static NestableFieldValidator fv(final Class<?> cls, final boolean notNull) {
        return new NestableFieldValidator() {
            @Override
            public void validateField(String pd, String name, Object field)
                    throws IllegalArgumentException {
                if (field == null) {
                    if (notNull) {
                        throw new IllegalArgumentException("Field " + name + " must not be null");
                    } else {
                        return;
                    }
                }
                if (!cls.isInstance(field)) {
                    throw new IllegalArgumentException(
                            pd + name + " must be a " + cls.getName() + ". (" + field + ")");
                }
            }
        };
    }

    /**
     * Returns a new NestableFieldValidator for a List of the given Class.
     *
     * @param cls     the Class of elements composing the list
     * @param notNull whether or not a value of null is valid
     * @return a NestableFieldValidator for a list of the given class

View on GitHub (pinned to 820761864e)

Solutions

1. Set the missing field in the configuration file or properties map passed to validateConfig
2. Provide an environment variable or default so the field is populated before validation
3. Add a default value in the config class constructor if the field is legitimately optional, and mark it notNull only when truly required

Example fix

// before: broker.conf missing required field
# clusterName=
// after
clusterName=my-cluster

// before validateConfig
for (String required : new String[]{"clusterName", "serviceUrl"}) {
    if (conf.get(required) == null) throw new IllegalStateException("missing required config: " + required);
}

try {
    ConfigValidation.validateConfig(conf);
} catch (IllegalArgumentException e) {
    throw new IllegalStateException("Invalid configuration: " + e.getMessage(), e);
}

When it happens

Trigger: Validating a config bean (e.g. via ConfigValidation.validateConfig on a Pulsar configuration class) where a field annotated with a notNull field validator is left null because it was absent from the properties/config file and has no default.

Common situations: A required setting (e.g. a service URL or cluster name) omitted from broker.conf/standalone.conf or the environment; a field with no default value in the config class not supplied at startup.

Related errors

• ${pd}${name} must be a ${cls.getName()}. (${field})
• Field '${name}' must be a Positive Number
• Field '${name}' cannot be null!
• Field '${name}' with value '${o}' does not implement ${class
• Field '${name}' with value '${o}' does not implement any of

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