{"record":{"id":"a4955ce60a5e7968","repo":"chinabugotech/hutool","slug":"parse-with-format-error","errorCode":null,"errorMessage":"Parse [{}] with format [{}] error!","messagePattern":"Parse \\[(.+?)\\] with format \\[(.+?)\\] error!","errorType":"exception","errorClass":"DateException","httpStatus":null,"severity":"error","filePath":"hutool-core/src/main/java/cn/hutool/core/date/DateTime.java","lineNumber":1103,"sourceCode":"\tprivate static Date parse(CharSequence dateStr, DateFormat dateFormat) {\n\t\tAssert.notBlank(dateStr, \"Date String must be not blank !\");\n\t\ttry {\n\t\t\treturn dateFormat.parse(dateStr.toString());\n\t\t} catch (Exception e) {\n\t\t\tString pattern;\n\t\t\tif (dateFormat instanceof SimpleDateFormat) {\n\t\t\t\tpattern = ((SimpleDateFormat) dateFormat).toPattern();\n\n\t\t\t\t// issue#3713 尝试使用US Locale解析\n\t\t\t\ttry {\n\t\t\t\t\treturn DateUtil.newSimpleFormat(pattern, Locale.US, null).parse(dateStr.toString());\n\t\t\t\t} catch (Exception ignore) {\n\t\t\t\t\t// ignore\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tpattern = dateFormat.toString();\n\t\t\t}\n\t\t\tthrow new DateException(StrUtil.format(\"Parse [{}] with format [{}] error!\", dateStr, pattern), e);\n\t\t}\n\t}\n\n\t/**\n\t * 转换字符串为Date\n\t *\n\t * @param dateStr 日期字符串\n\t * @param parser  {@link FastDateFormat}\n\t * @param lenient 是否宽容模式\n\t * @return {@link Calendar}\n\t */\n\tprivate static Calendar parse(CharSequence dateStr, DateParser parser, boolean lenient) {\n\t\tAssert.notNull(parser, \"Parser or DateFromat must be not null !\");\n\t\tAssert.notBlank(dateStr, \"Date String must be not blank !\");\n\n\t\tfinal Calendar calendar = CalendarUtil.parse(dateStr, lenient, parser);\n\t\tif (null == calendar) {\n\t\t\tthrow new DateException(\"Parse [{}] with format [{}] error!\", dateStr, parser.getPattern());","sourceCodeStart":1085,"sourceCodeEnd":1121,"githubUrl":"https://github.com/chinabugotech/hutool/blob/8870454b2a0c29cc6ffd31dcf5667c8ceb2fc442/hutool-core/src/main/java/cn/hutool/core/date/DateTime.java#L1085-L1121","documentation":"Thrown by the private DateTime.parse(CharSequence, DateFormat) overload when dateFormat.parse() throws an exception and a fallback attempt with Locale.US also fails. The message includes the date string and the detected pattern. This wraps any underlying ParseException into a DateException with context. Note the inner fallback retry with Locale.US (issue#3713) for locale-sensitive parsing.","triggerScenarios":"Parsing a date string with a SimpleDateFormat whose pattern does not match (e.g., \"2024/01/15\" with pattern \"yyyy-MM-dd\"). Locale-sensitive month names (e.g., \"Jan\" parsed with a non-English locale and the US fallback also fails). A corrupted or malformed date string.","commonSituations":"Configured date format pattern does not match incoming data format. Locale mismatch: data has English month names but the system or configured locale is non-English (and vice versa). Data quality issues: strings that look like dates but have extra characters, wrong separators, or encoding problems.","solutions":["Verify the date string matches the format pattern: log both and compare character-by-character.","Add locale explicitly when creating the DateFormat: DateUtil.newSimpleFormat(pattern, Locale.US, null).","Provide multiple format patterns and try each, or use parseByPatterns() for multi-pattern attempts.","Sanitize the input string (trim whitespace, normalize separators) before parsing.","Catch DateException at the call site and apply a fallback parsing strategy."],"exampleFix":"// before\nDateTime dt = DateUtil.parse(dateStr, new SimpleDateFormat(\"yyyy-MM-dd\"));\n// throws if dateStr is \"2024/01/15\"\n\n// after\nDateTime dt = DateUtil.parse(dateStr,\n    new SimpleDateFormat(\"yyyy-MM-dd\"),\n    new SimpleDateFormat(\"yyyy/MM/dd\"));\n// or catch and retry:\ntry {\n    dt = DateUtil.parse(dateStr, fmt);\n} catch (DateException e) {\n    dt = DateUtil.parse(dateStr, fallbackFmt);\n}","handlingStrategy":"try-catch","validationCode":"// Pre-validate: check string matches expected format\ntry {\n    new SimpleDateFormat(expectedPattern).parse(dateStr);\n} catch (ParseException e) {\n    // pattern mismatch; try alternative patterns\n}","typeGuard":null,"tryCatchPattern":"try {\n    return DateUtil.parse(dateStr, dateFormat);\n} catch (DateException e) {\n    // retry with alternative format or locale\n    return DateUtil.parse(dateStr, fallbackFormat);\n}","preventionTips":["Match the SimpleDateFormat pattern exactly to the input string format.","Set the locale explicitly on SimpleDateFormat for locale-sensitive data.","Provide fallback patterns and retry on parse failure.","Sanitize input strings (trim, normalize separators) before parsing."],"tags":["date","datetime","parse","format-mismatch","locale","date-exception"],"backgroundTag":null,"analyzedSha":"8870454b2a0c29cc6ffd31dcf5667c8ceb2fc442","analyzedAt":"2026-08-14T04:01:12.892Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}