google/gson · error · IllegalArgumentException

The date pattern '{pattern}' is not valid

Error message

The date pattern '{pattern}' is not valid

What it means

Thrown by GsonBuilder.setDateFormat(String) when the pattern is non-null but not a valid SimpleDateFormat pattern (new SimpleDateFormat(pattern) throws IllegalArgumentException internally). The pattern governs serialization/deserialization of java.util.Date (and java.sql Date/Timestamp when present). The original IllegalArgumentException is chained as the cause. This is a configuration-time error.

Source

Thrown at gson/src/main/java/com/google/gson/GsonBuilder.java:645

   *
   * <p>Note that this pattern must abide by the convention provided by {@code SimpleDateFormat}
   * class. See the documentation in {@link SimpleDateFormat} for more information on valid date and
   * time patterns.
   *
   * @param pattern the pattern that dates will be serialized/deserialized to/from; can be {@code
   *     null} to reset the pattern
   * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
   * @throws IllegalArgumentException if the pattern is invalid
   * @since 1.2
   */
  @CanIgnoreReturnValue
  public GsonBuilder setDateFormat(String pattern) {
    if (pattern != null) {
      try {
        SimpleDateFormat unused = new SimpleDateFormat(pattern);
      } catch (IllegalArgumentException e) {
        // Throw exception if it is an invalid date format
        throw new IllegalArgumentException("The date pattern '" + pattern + "' is not valid", e);
      }
    }
    this.datePattern = pattern;
    return this;
  }

  /**
   * Configures Gson to serialize {@code Date} objects according to the date style value provided.
   * You can call this method or {@link #setDateFormat(String)} multiple times, but only the last
   * invocation will be used to decide the serialization format. This methods leaves the current
   * 'time style' unchanged.
   *
   * <p>Note that this style value should be one of the predefined constants in the {@link
   * DateFormat} class, such as {@link DateFormat#MEDIUM}. See the documentation of the {@link
   * DateFormat} class for more information on the valid style constants.
   *
   * @deprecated Counterintuitively, despite this method taking only a 'date style' Gson will use a
   *     format which includes both date and time, with the 'time style' being the last value set by

View on GitHub (pinned to 8b8628c656)

Solutions

1. Use a valid SimpleDateFormat pattern; reference the SimpleDateFormat Javadoc for legal letters (e.g. "yyyy-MM-dd'T'HH:mm:ss.SSSZ").
2. Quote literal text with single quotes, e.g. "yyyy-MM-dd'T'HH:mm:ss".
3. If unsure, test the pattern standalone: new SimpleDateFormat(pattern) before wiring it into GsonBuilder.
4. For null (reset to default), pass null explicitly rather than an empty string.

Example fix

// before: invalid pattern
new GsonBuilder().setDateFormat("yyyy-MM-dd HH:mm:ss [Z]").create(); // throws: brackets invalid

// after: valid SimpleDateFormat pattern
new GsonBuilder().setDateFormat("yyyy-MM-dd HH:mm:ss.SSS").create();
// or reset to default
new GsonBuilder().setDateFormat(null).create();

// Validate the pattern standalone before wiring into GsonBuilder
static String validateDatePattern(String pattern) {
  if (pattern == null) return null; // reset
  try { new SimpleDateFormat(pattern); return pattern; }
  catch (IllegalArgumentException e) {
    throw new IllegalArgumentException("Bad date pattern: " + pattern, e);
  }
}
new GsonBuilder().setDateFormat(validateDatePattern(configPattern)).create();

static boolean isValidDatePattern(String pattern) {
  if (pattern == null) return true;
  try { new SimpleDateFormat(pattern); return true; }
  catch (IllegalArgumentException e) { return false; }
}

When it happens

Trigger: Passing a malformed pattern like "yyyy-MM-dd HH:mm:ss EXTRA" with illegal letters, unmatched quotes, or unknown pattern letters; typos like "YYY" vs "yyyy" sometimes tolerated but invalid tokens rejected; locale-specific patterns under the wrong Locale; passing an empty string "" (not a valid pattern).

Common situations: Patterns sourced from config files with typos or stray characters; copy-paste of patterns between libraries with different syntax (e.g. ISO-8601 vs Moment.js vs Java); locale-sensitive letters under unsupported locales; migration from java.time DateTimeFormatter patterns which differ from SimpleDateFormat.

Related errors

• Invalid version: {version}
• Invalid style: {style}
• Only combinations of \n and \r are allowed in newline.
• Only combinations of spaces and tabs are allowed in indent.
• Invalid nesting limit: " + limit

AI-assisted analysis of google/gson@8b8628c656 (2026-08-04). Data as JSON: /data/errors/9a3749c115310976.json. Report an issue: GitHub.