chinabugotech/hutool · error · DateException

Parse [{}] with format [{}] error!

Error message

Parse [{}] with format [{}] error!

What it means

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.

Source

Thrown at hutool-core/src/main/java/cn/hutool/core/date/DateTime.java:1103

	private static Date parse(CharSequence dateStr, DateFormat dateFormat) {
		Assert.notBlank(dateStr, "Date String must be not blank !");
		try {
			return dateFormat.parse(dateStr.toString());
		} catch (Exception e) {
			String pattern;
			if (dateFormat instanceof SimpleDateFormat) {
				pattern = ((SimpleDateFormat) dateFormat).toPattern();

				// issue#3713 尝试使用US Locale解析
				try {
					return DateUtil.newSimpleFormat(pattern, Locale.US, null).parse(dateStr.toString());
				} catch (Exception ignore) {
					// ignore
				}
			} else {
				pattern = dateFormat.toString();
			}
			throw new DateException(StrUtil.format("Parse [{}] with format [{}] error!", dateStr, pattern), e);
		}
	}

	/**
	 * 转换字符串为Date
	 *
	 * @param dateStr 日期字符串
	 * @param parser  {@link FastDateFormat}
	 * @param lenient 是否宽容模式
	 * @return {@link Calendar}
	 */
	private static Calendar parse(CharSequence dateStr, DateParser parser, boolean lenient) {
		Assert.notNull(parser, "Parser or DateFromat must be not null !");
		Assert.notBlank(dateStr, "Date String must be not blank !");

		final Calendar calendar = CalendarUtil.parse(dateStr, lenient, parser);
		if (null == calendar) {
			throw new DateException("Parse [{}] with format [{}] error!", dateStr, parser.getPattern());

View on GitHub (pinned to 8870454b2a)

Solutions

1. Verify the date string matches the format pattern: log both and compare character-by-character.
2. Add locale explicitly when creating the DateFormat: DateUtil.newSimpleFormat(pattern, Locale.US, null).
3. Provide multiple format patterns and try each, or use parseByPatterns() for multi-pattern attempts.
4. Sanitize the input string (trim whitespace, normalize separators) before parsing.
5. Catch DateException at the call site and apply a fallback parsing strategy.

Example fix

// before
DateTime dt = DateUtil.parse(dateStr, new SimpleDateFormat("yyyy-MM-dd"));
// throws if dateStr is "2024/01/15"

// after
DateTime dt = DateUtil.parse(dateStr,
    new SimpleDateFormat("yyyy-MM-dd"),
    new SimpleDateFormat("yyyy/MM/dd"));
// or catch and retry:
try {
    dt = DateUtil.parse(dateStr, fmt);
} catch (DateException e) {
    dt = DateUtil.parse(dateStr, fallbackFmt);
}

// Pre-validate: check string matches expected format
try {
    new SimpleDateFormat(expectedPattern).parse(dateStr);
} catch (ParseException e) {
    // pattern mismatch; try alternative patterns
}

try {
    return DateUtil.parse(dateStr, dateFormat);
} catch (DateException e) {
    // retry with alternative format or locale
    return DateUtil.parse(dateStr, fallbackFormat);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unable to parse the date: {}
• This is not a mutable object !
• Date and Patterns must not be null
• ERA is not support offset!
• Date to compare is null !

AI-assisted analysis of chinabugotech/hutool@8870454b2a (2026-08-14). Data as JSON: /api/errors/a4955ce60a5e7968. Report an issue: GitHub.