{"id":"861d76cc6e71b543","repo":"apache/kafka","slug":"invalid-value-for-configuration-the-value","errorCode":null,"errorMessage":"Invalid value `{}` for configuration {}. The value must be either 'earliest', 'latest', 'none' or of the format 'by_duration:'.","messagePattern":"Invalid value `(.+?)` for configuration (.+?)\\. The value must be either 'earliest', 'latest', 'none' or of the format 'by_duration:'\\.","errorType":"validation","errorClass":"org.apache.kafka.common.config.ConfigException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/consumer/internals/AutoOffsetResetStrategy.java","lineNumber":165,"sourceCode":" return Objects.hash(type, duration);\n }\n\n @Override\n public String toString() {\n return \"AutoOffsetResetStrategy{\" +\n \"type=\" + type +\n (duration.map(value -> \", duration=\" + value).orElse(\"\")) +\n '}';\n }\n\n public static class Validator implements ConfigDef.Validator {\n @Override\n public void ensureValid(String name, Object value) {\n String offsetStrategy = (String) value;\n try {\n fromString(offsetStrategy);\n } catch (Exception e) {\n throw new ConfigException(name, value, \"Invalid value `\" + offsetStrategy + \"` for configuration \" +\n name + \". The value must be either 'earliest', 'latest', 'none' or of the format 'by_duration:'.\");\n }\n }\n\n @Override\n public String toString() {\n String values = Arrays.stream(StrategyType.values())\n .map(strategyType -> {\n if (strategyType == StrategyType.BY_DURATION) {\n return \"by_duration:PnDTnHnMn.nS\";\n }\n return strategyType.toString();\n }).collect(Collectors.joining(\", \"));\n return \"[\" + values + \"]\";\n }\n }\n}\n","sourceCodeStart":147,"sourceCodeEnd":183,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/consumer/internals/AutoOffsetResetStrategy.java#L147-L183","documentation":"Thrown by AutoOffsetResetStrategy.Validator.ensureValid when the configured value for auto.offset.reset (or equivalent) cannot be parsed into one of the accepted strategies. The validator calls AutoOffsetResetStrategy.fromString, which accepts the literal strings 'earliest', 'latest', 'none', or 'by_duration:' followed by a valid ISO-8601 duration (PnDTnHnMn.nS). Any other value (typo, wrong case, malformed duration, negative duration, or the bare 'by_duration' without a duration suffix) is rejected and wrapped into a ConfigException at validation time, before the consumer is constructed.","triggerScenarios":"Constructing a KafkaConsumer (or any client that runs ConfigDef validation) with an auto.offset.reset property that is not exactly 'earliest', 'latest', 'none', or 'by_duration:'. Also triggered by setting the bare string 'by_duration' with no duration suffix (fromString throws), a negative duration (e.g. by_duration:PT-1H), or a non-ISO duration string (e.g. by_duration:1hour).","commonSituations":"Typos such as 'earlist' or 'lastest'; using uppercase 'EARLIEST' (only lowercase is accepted); passing 'none ' with trailing whitespace; using the new by_duration feature on a broker/client older than the version that introduced it; mis-copying the ISO-8601 duration format; passing a plain integer or a human duration like '5m' instead of 'PT5M'.","solutions":["Set auto.offset.reset to one of the exact literals 'earliest', 'latest', or 'none' (lowercase, no whitespace).","If you want a by-duration reset, use the exact format 'by_duration:PnDTnHnMn.nS' (e.g. 'by_duration:PT5M', 'by_duration:P1DT2H').","Trim any trailing/leading whitespace and confirm casing in your config source (properties file, env var, command line).","Verify you are running a client version that supports by_duration if you intend to use it; older clients only accept earliest/latest/none."],"exampleFix":"// before\nprops.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, \"lastest\");\nprops.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, \"by_duration:5m\");\n\n// after\nprops.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, \"latest\");\nprops.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, \"by_duration:PT5M\");","handlingStrategy":"validation","validationCode":"// Validate auto.offset.reset before building the consumer\nimport java.time.Duration;\nimport java.util.Locale;\nimport java.util.Set;\nimport java.util.regex.Pattern;\n\nprivate static final Set NAMED = Set.of(\"earliest\", \"latest\", \"none\");\n// ISO-8601 duration, e.g. P1DT2H3M4.5S (must be non-negative)\nprivate static final Pattern ISO_DURATION =\n Pattern.compile(\"^P(?!$)(\\\\d+Y)?(\\\\d+M)?(\\\\d+W)?(\\\\d+D)?(T(?=.*\\\\d)(\\\\d+H)?(\\\\d+M)?(\\\\d+(\\\\.\\\\d+)?S)?)?$\");\n\nstatic String normalizeAutoOffsetReset(String raw) {\n if (raw == null) throw new IllegalArgumentException(\"auto.offset.reset is null\");\n String v = raw.trim().toLowerCase(Locale.ROOT);\n if (NAMED.contains(v)) return v;\n if (v.startsWith(\"by_duration:\")) {\n String iso = v.substring(\"by_duration:\".length());\n if (!ISO_DURATION.matcher(iso).matches())\n throw new IllegalArgumentException(\"Malformed ISO-8601 duration: \" + iso);\n Duration d = Duration.parse(iso);\n if (d.isNegative())\n throw new IllegalArgumentException(\"Duration must be non-negative: \" + d);\n return v;\n }\n throw new IllegalArgumentException(\n \"auto.offset.reset must be 'earliest', 'latest', 'none', or 'by_duration:'; got: \" + raw);\n}\n\n// Usage: normalizeAutoOffsetReset(props.getProperty(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG));\n// then pass props to new KafkaConsumer<>(props, ...)","typeGuard":"// Type guard: narrow a free-form config value to a known-good literal union\n// (TypeScript-style shown for cross-language clarity; in Java use an enum)\n//\n// TypeScript:\n// type AutoOffsetReset = 'earliest' | 'latest' | 'none' | `by_duration:${string}`;\n// function isAutoOffsetReset(v: unknown): v is AutoOffsetReset {\n// if (typeof v !== 'string') return false;\n// const s = v.trim().toLowerCase();\n// if (['earliest','latest','none'].includes(s)) return true;\n// if (s.startsWith('by_duration:'))\n// return /^P(?!$)(\\d+Y)?(\\d+M)?(\\d+W)?(\\d+D)?(T(?=.*\\d)(\\d+H)?(\\d+M)?(\\d+(\\.\\d+)?S)?)?$/.test(s.slice('by_duration:'.length));\n// return false;\n// }\n//\n// Java enum equivalent:\n// enum AutoOffsetReset { EARLIEST, LATEST, NONE; }\n// // validate at the config boundary, store as enum, never as raw String downstream","tryCatchPattern":"// Construction-time config errors surface as ConfigException wrapped in KafkaException\ntry {\n Consumer consumer = new KafkaConsumer<>(props, keyDeser, valDeser);\n} catch (KafkaException e) {\n Throwable cause = e.getCause();\n if (cause instanceof ConfigException) {\n // log, alert, fail fast with the offending property name\n log.error(\"Invalid consumer config ({}); fix {} in configuration and restart\",\n cause.getMessage(), ConsumerConfig.AUTO_OFFSET_RESET_CONFIG);\n }\n throw e; // construction failure is unrecoverable for this instance\n}","preventionTips":["Source auto.offset.reset from a typed enum or constants, never from an unvalidated string.","Keep a unit test that asserts every named strategy ('earliest','latest','none') round-trips through AutoOffsetResetStrategy.fromString.","For 'by_duration', validate the ISO-8601 segment with Duration.parse in a pre-flight check at app startup, not at first poll.","Treat any ConfigException during KafkaConsumer construction as a deployment-blocking config error; surface it to operators, don't silently default."],"tags":["configuration","consumer","offset-reset","validation"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}