GoogleContainerTools/jib · error · IllegalArgumentException

${fieldName} must be a number of milliseconds since epoch or

Error message

${fieldName} must be a number of milliseconds since epoch or an ISO 8601 formatted date

What it means

Jib CLI's Instants.fromMillisOrIso8601 accepts either epoch milliseconds or an ISO 8601 date string for fields like creation/modification times. If DateTimeFormatter.parse fails with DateTimeParseException after the numeric (millis) branch also failed, it throws IllegalArgumentException with this message naming the field.

Source

Thrown at jib-cli/src/main/java/com/google/cloud/tools/jib/cli/Instants.java:52

   * @param fieldName name of field being parsed (for error messaging)
   * @return Instant value of parsed time
   */
  public static Instant fromMillisOrIso8601(String time, String fieldName) {
    try {
      return Instant.ofEpochMilli(Long.parseLong(time));
    } catch (NumberFormatException nfe) {
      // TODO: copied from PluginConfigurationProcessor, find a way to share better
      try {
        DateTimeFormatter formatter =
            new DateTimeFormatterBuilder()
                .append(DateTimeFormatter.ISO_DATE_TIME)
                .optionalStart()
                .appendOffset("+HHmm", "+0000")
                .optionalEnd()
                .toFormatter();
        return formatter.parse(time, Instant::from);
      } catch (DateTimeParseException dtpe) {
        throw new IllegalArgumentException(
            fieldName
                + " must be a number of milliseconds since epoch or an ISO 8601 formatted date");
      }
    }
  }
}

View on GitHub (pinned to fb949e2676)

Solutions

1. Use a valid ISO 8601 string, e.g. 2024-01-15T10:30:00Z.
2. Use epoch milliseconds, e.g. 1705314600000.
3. Trim whitespace/quotes from the value in your config or script before passing it.
4. Check the error message for the exact fieldName and fix that field's value.

Example fix

// before
creationTime = "01/15/2024"
// after
creationTime = "2024-01-15T00:00:00Z"

boolean validInstant(String v) {
  if (v == null) return false;
  try { Long.parseLong(v.trim()); return true; }
  catch (NumberFormatException ignored) {}
  try { java.time.Instant.parse(v.trim()); return true; }
  catch (java.time.format.DateTimeParseException e) { return false; }
}

try {
  jibBuild(config);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("must be a number of milliseconds since epoch or an ISO 8601")) {
    log.error("Fix time field value in config: {}", e.getMessage());
  } else throw e;
}

When it happens

Trigger: Passing a value to a time field (e.g. in a build file or CLI option) that is neither a number of milliseconds since epoch nor an ISO 8601 formatted date, e.g. '2024-01-01' without time context is fine but 'yesterday' or '01/02/2024' is not.

Common situations: Using human-friendly date strings or locale formats (MM/DD/YYYY), copying timestamps with stray whitespace or trailing 'Z' mismatches, config templating errors.

Related errors

• The class file (${jarEntry}) is of an invalid format.
• Reached end of class file (${jarEntry}) before being able to
• Missing option: --name must be specified when using --target
• octalPermissions must be a 3-digit octal number (000-777)
• The input JAR (${jarPath}) is compiled with Java ${jarJavaVe

AI-assisted analysis of GoogleContainerTools/jib@fb949e2676 (2026-09-06). Data as JSON: /api/errors/1b99d9c820515cf6. Report an issue: GitHub.