spring-projects/spring-boot · error · IllegalArgumentException

'%s' is not within the valid range %s to %s

Error message

'%s' is not within the valid range %s to %s

What it means

IllegalArgumentException thrown by MavenBuildOutputTimestamp.toFileTime's parse branch when the supplied ISO-8601 timestamp parses successfully but resolves to an Instant outside the permitted [DATE_MIN, DATE_MAX] window. The bound exists because Reproducible Builds requires a sane epoch range and extreme values would corrupt jar entries.

Source

Thrown at build-plugin/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/MavenBuildOutputTimestamp.java:92

	 * @return the parsed timestamp as an {@code Instant}, or {@code null}
	 * @throws IllegalArgumentException if the outputTimestamp is neither ISO 8601 nor an
	 * integer, or it's not within the valid range 1980-01-01T00:00:02Z to
	 * 2099-12-31T23:59:59Z
	 */
	@Nullable Instant toInstant() {
		if (!StringUtils.hasLength(this.timestamp)) {
			return null;
		}
		if (isNumeric(this.timestamp)) {
			return Instant.ofEpochSecond(Long.parseLong(this.timestamp));
		}
		if (this.timestamp.length() < 2) {
			return null;
		}
		try {
			Instant instant = OffsetDateTime.parse(this.timestamp).withOffsetSameInstant(ZoneOffset.UTC).toInstant();
			if (instant.isBefore(DATE_MIN) || instant.isAfter(DATE_MAX)) {
				throw new IllegalArgumentException(
						String.format("'%s' is not within the valid range %s to %s", instant, DATE_MIN, DATE_MAX));
			}
			return instant;
		}
		catch (DateTimeParseException pe) {
			throw new IllegalArgumentException(String.format("Can't parse '%s' to instant", this.timestamp));
		}
	}

	private static boolean isNumeric(String str) {
		for (char c : str.toCharArray()) {
			if (!Character.isDigit(c)) {
				return false;
			}
		}
		return true;
	}

View on GitHub (pinned to 270dfe353f)

Solutions

1. Set <project.build.outputTimestamp> to a value within the documented reproducible-builds window (typically after 1980).
2. Use the epoch-seconds numeric form for deterministic builds, e.g. <outputTimestamp>1700000000</outputTimestamp>.
3. Omit the property entirely (null/empty returns null from toFileTime) if reproducible timestamps aren't required.
4. Check the SOURCE_DATE_EPOCH environment variable feeding the timestamp.

Example fix

// before: <project.build.outputTimestamp>1970-01-01T00:00:00Z</project.build.outputTimestamp>
// after:  <project.build.outputTimestamp>2024-01-01T00:00:00Z</project.build.outputTimestamp>

// Validate the outputTimestamp window before repackage/build-image:
Instant t = OffsetDateTime.parse(outputTimestamp).withOffsetSameInstant(ZoneOffset.UTC).toInstant();
if (t.isBefore(DATE_MIN) || t.isAfter(DATE_MAX)) {
    throw new IllegalArgumentException(outputTimestamp + " outside " + DATE_MIN + ".." + DATE_MAX);
}

try {
    // invoke goal that calls toFileTime
} catch (IllegalArgumentException ex) {
    if (ex.getMessage().contains("not within the valid range")) {
        // move outputTimestamp inside the window and retry
    }
    throw ex;
}

When it happens

Trigger: Setting <project.build.outputTimestamp> (or the plugin's <outputTimestamp>) to an ISO-8601 string that is earlier than DATE_MIN or later than DATE_MAX after conversion to UTC.

Common situations: Using a CI-injected timestamp like '1970-01-01T00:00:00Z' that predates DATE_MIN; misconfigured SOURCE_DATE_EPOCH rollover producing a far-future date; copy-pasting a timestamp from a different timezone that shifts out of range.

Related errors

• Can't parse '%s' to instant
• Invalid value for parameter 'outputTimestamp'
• Failed to load layers configuration with name '%s': '%s' not
• Failed to generate build-info.properties. {ex.getMessage()}
• Invalid Docker configuration, either context or host can be

AI-assisted analysis of spring-projects/spring-boot@270dfe353f (2026-08-11). Data as JSON: /api/errors/4441adb08ba09ac7. Report an issue: GitHub.