Java DateTimeException Class
Last modified: April 16, 2025
The java.time.DateTimeException is a runtime exception thrown when
date-time operations fail. It indicates invalid date, time, or time-zone data.
This exception is unchecked, meaning it doesn't need to be declared in throws.
DateTimeException extends RuntimeException. It's used
throughout the java.time package. Common cases include invalid date values,
unsupported fields, and parsing errors. The exception provides detailed messages.
DateTimeException Class Overview
DateTimeException is thrown by methods in the java.time API. It
replaces the older IllegalArgumentException for date-time issues.
The class helps identify specific problems with temporal data.
public class DateTimeException extends RuntimeException {
public DateTimeException(String message);
public DateTimeException(String message, Throwable cause);
}
The code shows the DateTimeException class structure. It provides standard exception constructors. The message describes the error, while cause tracks underlying exceptions. This helps with debugging temporal problems.
Invalid Date Example
This example demonstrates DateTimeException when creating an invalid date. The LocalDate class throws it when day exceeds month's maximum days.
package com.zetcode;
import java.time.LocalDate;
public class Main {
public static void main(String[] args) {
try {
// February 30 doesn't exist
LocalDate invalidDate = LocalDate.of(2025, 2, 30);
System.out.println("Created date: " + invalidDate);
} catch (DateTimeException e) {
System.out.println("Error: " + e.getMessage());
}
}
}
The code attempts to create February 30, which is invalid. DateTimeException is thrown with a message about invalid value for day. The catch block handles the exception gracefully.
Invalid Time Example
This example shows DateTimeException for invalid time values. LocalTime throws it when hour exceeds 23 or minute exceeds 59.
package com.zetcode;
import java.time.LocalTime;
public class Main {
public static void main(String[] args) {
try {
// 25:00 is not a valid time
LocalTime invalidTime = LocalTime.of(25, 0);
System.out.println("Created time: " + invalidTime);
} catch (DateTimeException e) {
System.out.println("Error: " + e.getMessage());
}
}
}
The code tries to create a time of 25:00 which doesn't exist. DateTimeException is thrown with details about invalid hour value. The exception prevents creation of invalid time objects.
Parsing Error Example
DateTimeException occurs when parsing malformed date-time strings. The parse methods throw it when input doesn't match expected format.
package com.zetcode;
import java.time.LocalDateTime;
public class Main {
public static void main(String[] args) {
try {
// Missing time component
LocalDateTime parsed = LocalDateTime.parse("2025-04-16");
System.out.println("Parsed datetime: " + parsed);
} catch (DateTimeException e) {
System.out.println("Parse error: " + e.getMessage());
}
}
}
The code attempts to parse an incomplete date-time string. DateTimeException is thrown because the string lacks required time information. The message indicates text couldn't be parsed.
Unsupported Field Example
DateTimeException is thrown when using unsupported temporal fields. Each date-time class supports specific fields only.
package com.zetcode;
import java.time.LocalTime;
import java.time.temporal.ChronoField;
public class Main {
public static void main(String[] args) {
try {
LocalTime time = LocalTime.now();
// DayOfMonth not supported for LocalTime
int day = time.get(ChronoField.DAY_OF_MONTH);
System.out.println("Day: " + day);
} catch (DateTimeException e) {
System.out.println("Field error: " + e.getMessage());
}
}
}
The code tries to get day-of-month from a LocalTime object. DateTimeException is thrown because time objects don't support date fields. The message indicates unsupported field.
Time Zone Example
DateTimeException occurs with invalid time zone operations. This example shows it when using invalid zone offset values.
package com.zetcode;
import java.time.ZoneOffset;
public class Main {
public static void main(String[] args) {
try {
// Offset exceeds maximum (+18:00)
ZoneOffset invalidOffset = ZoneOffset.ofHours(20);
System.out.println("Offset: " + invalidOffset);
} catch (DateTimeException e) {
System.out.println("Zone error: " + e.getMessage());
}
}
}
The code attempts to create a zone offset of +20 hours. DateTimeException is thrown because offsets must be between -18 and +18. The message explains the valid range.
Duration Calculation Example
DateTimeException can occur during duration calculations. This happens when operations exceed supported ranges.
package com.zetcode;
import java.time.Duration;
import java.time.LocalTime;
public class Main {
public static void main(String[] args) {
try {
LocalTime start = LocalTime.of(23, 0);
LocalTime end = LocalTime.of(1, 0);
// Fails because duration would cross midnight
Duration duration = Duration.between(start, end);
System.out.println("Duration: " + duration);
} catch (DateTimeException e) {
System.out.println("Duration error: " + e.getMessage());
}
}
}
The code calculates duration between times crossing midnight. DateTimeException is thrown because LocalTime can't represent durations over 24 hours. The message indicates the calculation limitation.
Custom DateTimeException Example
This example shows how to throw DateTimeException in custom date-time logic. It's useful for validating business rules.
package com.zetcode;
import java.time.DateTimeException;
import java.time.LocalDate;
public class Main {
public static void main(String[] args) {
try {
validateFutureDate(LocalDate.of(2020, 1, 1));
} catch (DateTimeException e) {
System.out.println("Validation failed: " + e.getMessage());
}
}
static void validateFutureDate(LocalDate date) {
if (date.isBefore(LocalDate.now())) {
throw new DateTimeException("Date must be in the future");
}
System.out.println("Valid future date: " + date);
}
}
The code validates that dates are in the future. It throws DateTimeException for past dates. This demonstrates custom use of the exception for business rules.
Source
Java DateTimeException Class Documentation
This tutorial covered DateTimeException with practical examples. The exception helps handle date-time errors consistently. Understanding it is key for robust temporal operations in Java.
Author
List all Java tutorials.