chinabugotech/hutool · error · DateException

Unable to parse the date: {}

Error message

Unable to parse the date: {}

What it means

Thrown by CalendarUtil.parseByPatterns() after the loop exhausts all provided patterns without successfully parsing the date string. Each pattern is tried with FastDateParser; if none parse the string fully (pos.getIndex() == str.length()), DateException is thrown. This means the string format does not match any supplied pattern.

Source

Thrown at hutool-core/src/main/java/cn/hutool/core/date/CalendarUtil.java:824

					continue;
				}
				calendar.setTime(parse);
				return calendar;
			}

			final FastDateParser fdp = new FastDateParser(parsePattern, tz, lcl);
			calendar.clear();
			try {
				if (fdp.parse(str, pos, calendar) && pos.getIndex() == str.length()) {
					return calendar;
				}
			} catch (final IllegalArgumentException ignore) {
				// leniency is preventing calendar from being set
			}
			pos.setIndex(0);
		}

		throw new DateException("Unable to parse the date: {}", str);
	}

	/**
	 * 使用指定{@link DateParser}解析字符串为{@link Calendar}
	 *
	 * @param str     日期字符串
	 * @param lenient 是否宽容模式
	 * @param parser  {@link DateParser}
	 * @return 解析后的 {@link Calendar}，解析失败返回{@code null}
	 * @since 5.7.14
	 */
	public static Calendar parse(CharSequence str, boolean lenient, DateParser parser) {
		final Calendar calendar = Calendar.getInstance(parser.getTimeZone(), parser.getLocale());
		calendar.clear();
		calendar.setLenient(lenient);

		return parser.parse(StrUtil.str(str), new ParsePosition(0), calendar) ? calendar : null;
	}

View on GitHub (pinned to 8870454b2a)

Solutions

1. Add more patterns to cover all expected input formats, e.g., include both "yyyy-MM-dd HH:mm:ss" and "yyyy-MM-dd'T'HH:mm:ss".
2. Verify the date string format by logging it before parsing, then match patterns accordingly.
3. Try lenient mode (pass true for lenient) to allow more flexible parsing.
4. Pre-normalize the input string (e.g., replace 'T' with space, trim, convert locale-specific month names) before parsing.
5. Use DateTimeFormatter or DateUtil.parse() with a known single format if the input format is deterministic.

Example fix

// before
Calendar cal = CalendarUtil.parseByPatterns("2024-01-15T10:30:00", "yyyy-MM-dd");
// throws: time portion not consumed

// after
Calendar cal = CalendarUtil.parseByPatterns("2024-01-15T10:30:00",
    "yyyy-MM-dd'T'HH:mm:ss", "yyyy-MM-dd HH:mm:ss", "yyyy-MM-dd");

// Pre-check: verify the string likely matches at least one pattern
boolean matches = false;
for (String p : parsePatterns) {
    try {
        new SimpleDateFormat(p).parse(str);
        matches = true; break;
    } catch (ParseException ignored) {}
}
if (!matches) {
    // add more patterns or reject
}

try {
    return CalendarUtil.parseByPatterns(str, locale, true, patterns);
} catch (DateException e) {
    // try lenient mode or additional patterns
    return CalendarUtil.parseByPatterns(str, locale, true, extraPatterns);
}

When it happens

Trigger: Calling parseByPatterns("2024-01-15T10:30:00", "yyyy-MM-dd") — the time portion causes incomplete parse. Calling parseByPatterns("15/01/2024", "yyyy-MM-dd") — day/month order mismatch. Providing patterns that do not match the locale-specific separators or field widths in the input string.

Common situations: Internationalization: date strings from different locales (US MM/dd/yyyy vs EU dd/MM/yyyy). User-entered dates with ambiguous formats. API responses with unexpected date formats (ISO-8601 with 'T' separator vs space). Strict (non-lenient) mode rejecting otherwise-close matches.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Date and Patterns must not be null
• Parse [{}] with format [{}] error!
• The date must not be null
• Birthday is after dateToCompare!
• This is not a mutable object !

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