apache/pulsar · error · IllegalArgumentException

%s value %d doesn't fit in given range (%d, %d),

Error message

%s value %d doesn't fit in given range (%d, %d),

What it means

isComplete validates FieldContext annotations on a configuration object's fields, including numeric range constraints ( minValue / maxValue ). When a numeric field's value falls outside the annotated range, the violations are accumulated and thrown as one IllegalArgumentException whose message is the concatenated per-field messages (each of the form '<field> value <v> doesn't fit in given range (<min>, <max>),').

Source

Thrown at pulsar-broker-common/src/main/java/org/apache/pulsar/common/configuration/PulsarConfigurationLoader.java:210

                boolean isRequired = field.getAnnotation(FieldContext.class).required();
                long minValue = field.getAnnotation(FieldContext.class).minValue();
                long maxValue = field.getAnnotation(FieldContext.class).maxValue();
                if (isRequired && isEmpty(value)) {
                    error.append(String.format("Required %s is null,", field.getName()));
                }

                if (value != null && Number.class.isAssignableFrom(value.getClass())) {
                    long fieldVal = ((Number) value).longValue();
                    boolean valid = fieldVal >= minValue && fieldVal <= maxValue;
                    if (!valid) {
                        error.append(String.format("%s value %d doesn't fit in given range (%d, %d),", field.getName(),
                                fieldVal, minValue, maxValue));
                    }
                }
            }
        }
        if (error.length() > 0) {
            throw new IllegalArgumentException(error.substring(0, error.length() - 1));
        }
        return true;
    }

    private static boolean isEmpty(Object obj) {
        if (obj == null) {
            return true;
        } else if (obj instanceof String) {
            return StringUtils.isBlank((String) obj);
        } else {
            return false;
        }
    }

    /**
     * Converts a PulsarConfiguration object to a ServiceConfiguration object.
     *
     * @param conf

View on GitHub (pinned to 820761864e)

Solutions

1. Read the field name and range from the exception message and set the value within (min, max)
2. Check units — a value in the wrong unit (ms vs seconds, bytes vs MB) often lands out of range
3. Validate your properties before startup by calling isComplete yourself in tests/scripts
4. Consult the configuration reference docs for the field's documented valid range

Example fix

# before (broker.conf)
brokerShutdownTimeoutMs=0
# after
brokerShutdownTimeoutMs=3000

// Pre-validate a numeric field against its FieldContext range
java.lang.reflect.Field f = ServiceConfiguration.class.getField("brokerShutdownTimeoutMs");
FieldContext ctx = f.getAnnotation(FieldContext.class);
long v = props.getProperty("brokerShutdownTimeoutMs") != null
    ? Long.parseLong(props.getProperty("brokerShutdownTimeoutMs")) : 0;
if (v < ctx.minValue() || v > ctx.maxValue()) {
    throw new IllegalArgumentException(f.getName() + "=" + v + " outside ("
        + ctx.minValue() + ", " + ctx.maxValue() + ")");
}

try {
    PulsarConfigurationLoader.isComplete(conf);
} catch (IllegalArgumentException e) {
    // message lists every out-of-range field with its (min, max)
    log.error("Configuration range violations: {}", e.getMessage());
    throw e;
}

When it happens

Trigger: Calling PulsarConfigurationLoader.isComplete (or create, which validates) with a properties object that sets a numeric configuration field to a value below the FieldContext minValue or above maxValue, or a required field left empty.

Common situations: Typo or wrong unit in a config value (e.g. 0 for a port, a retention number below the allowed minimum); copy-pasted configs from another deployment; negative values where positives are required; oversized values after unit changes.

Related errors

• Timeout during delete operation
• Timeout during close operation
• Timeout during open-cursor operation
• Timeout during delete-cursors operation
• Timeout during managed ledger terminate

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