{"record":{"id":"5e86dc863d030340","repo":"apache/pulsar","slug":"s-value-d-doesn-t-fit-in-given-range-d-d","errorCode":null,"errorMessage":"%s value %d doesn't fit in given range (%d, %d),","messagePattern":"(.+?) value (.+?) doesn't fit in given range \\((.+?), (.+?)\\),","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-broker-common/src/main/java/org/apache/pulsar/common/configuration/PulsarConfigurationLoader.java","lineNumber":210,"sourceCode":"                boolean isRequired = field.getAnnotation(FieldContext.class).required();\n                long minValue = field.getAnnotation(FieldContext.class).minValue();\n                long maxValue = field.getAnnotation(FieldContext.class).maxValue();\n                if (isRequired && isEmpty(value)) {\n                    error.append(String.format(\"Required %s is null,\", field.getName()));\n                }\n\n                if (value != null && Number.class.isAssignableFrom(value.getClass())) {\n                    long fieldVal = ((Number) value).longValue();\n                    boolean valid = fieldVal >= minValue && fieldVal <= maxValue;\n                    if (!valid) {\n                        error.append(String.format(\"%s value %d doesn't fit in given range (%d, %d),\", field.getName(),\n                                fieldVal, minValue, maxValue));\n                    }\n                }\n            }\n        }\n        if (error.length() > 0) {\n            throw new IllegalArgumentException(error.substring(0, error.length() - 1));\n        }\n        return true;\n    }\n\n    private static boolean isEmpty(Object obj) {\n        if (obj == null) {\n            return true;\n        } else if (obj instanceof String) {\n            return StringUtils.isBlank((String) obj);\n        } else {\n            return false;\n        }\n    }\n\n    /**\n     * Converts a PulsarConfiguration object to a ServiceConfiguration object.\n     *\n     * @param conf","sourceCodeStart":192,"sourceCodeEnd":228,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker-common/src/main/java/org/apache/pulsar/common/configuration/PulsarConfigurationLoader.java#L192-L228","documentation":"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>),').","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the field name and range from the exception message and set the value within (min, max)","Check units — a value in the wrong unit (ms vs seconds, bytes vs MB) often lands out of range","Validate your properties before startup by calling isComplete yourself in tests/scripts","Consult the configuration reference docs for the field's documented valid range"],"exampleFix":"# before (broker.conf)\nbrokerShutdownTimeoutMs=0\n# after\nbrokerShutdownTimeoutMs=3000","handlingStrategy":"validation","validationCode":"// Pre-validate a numeric field against its FieldContext range\njava.lang.reflect.Field f = ServiceConfiguration.class.getField(\"brokerShutdownTimeoutMs\");\nFieldContext ctx = f.getAnnotation(FieldContext.class);\nlong v = props.getProperty(\"brokerShutdownTimeoutMs\") != null\n    ? Long.parseLong(props.getProperty(\"brokerShutdownTimeoutMs\")) : 0;\nif (v < ctx.minValue() || v > ctx.maxValue()) {\n    throw new IllegalArgumentException(f.getName() + \"=\" + v + \" outside (\"\n        + ctx.minValue() + \", \" + ctx.maxValue() + \")\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    PulsarConfigurationLoader.isComplete(conf);\n} catch (IllegalArgumentException e) {\n    // message lists every out-of-range field with its (min, max)\n    log.error(\"Configuration range violations: {}\", e.getMessage());\n    throw e;\n}","preventionTips":["Read FieldContext minValue/maxValue annotations (or the config docs) before setting values","Run isComplete against candidate configs in CI before deployment","Watch for unit mismatches (ms/s, bytes/MB) that push values out of range"],"tags":["configuration","validation","range-check"],"backgroundTag":"config-value-out-of-range","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}