Note that this pattern must abide by the convention provided by {@code SimpleDateFormat}\n * class. See the documentation in {@link SimpleDateFormat} for more information on valid date and\n * time patterns.\n *\n * @param pattern the pattern that dates will be serialized/deserialized to/from; can be {@code\n * null} to reset the pattern\n * @return a reference to this {@code GsonBuilder} object to fulfill the \"Builder\" pattern\n * @throws IllegalArgumentException if the pattern is invalid\n * @since 1.2\n */\n @CanIgnoreReturnValue\n public GsonBuilder setDateFormat(String pattern) {\n if (pattern != null) {\n try {\n SimpleDateFormat unused = new SimpleDateFormat(pattern);\n } catch (IllegalArgumentException e) {\n // Throw exception if it is an invalid date format\n throw new IllegalArgumentException(\"The date pattern '\" + pattern + \"' is not valid\", e);\n }\n }\n this.datePattern = pattern;\n return this;\n }\n\n /**\n * Configures Gson to serialize {@code Date} objects according to the date style value provided.\n * You can call this method or {@link #setDateFormat(String)} multiple times, but only the last\n * invocation will be used to decide the serialization format. This methods leaves the current\n * 'time style' unchanged.\n *\n *
Note that this style value should be one of the predefined constants in the {@link\n * DateFormat} class, such as {@link DateFormat#MEDIUM}. See the documentation of the {@link\n * DateFormat} class for more information on the valid style constants.\n *\n * @deprecated Counterintuitively, despite this method taking only a 'date style' Gson will use a\n * format which includes both date and time, with the 'time style' being the last value set by","sourceCodeStart":627,"sourceCodeEnd":663,"githubUrl":"https://github.com/google/gson/blob/8b8628c65699bc4421696183c62ae0c1b9b281dc/gson/src/main/java/com/google/gson/GsonBuilder.java#L627-L663","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Use a valid SimpleDateFormat pattern; reference the SimpleDateFormat Javadoc for legal letters (e.g. \"yyyy-MM-dd'T'HH:mm:ss.SSSZ\").","Quote literal text with single quotes, e.g. \"yyyy-MM-dd'T'HH:mm:ss\".","If unsure, test the pattern standalone: new SimpleDateFormat(pattern) before wiring it into GsonBuilder.","For null (reset to default), pass null explicitly rather than an empty string."],"exampleFix":"// before: invalid pattern\nnew GsonBuilder().setDateFormat(\"yyyy-MM-dd HH:mm:ss [Z]\").create(); // throws: brackets invalid\n\n// after: valid SimpleDateFormat pattern\nnew GsonBuilder().setDateFormat(\"yyyy-MM-dd HH:mm:ss.SSS\").create();\n// or reset to default\nnew GsonBuilder().setDateFormat(null).create();","handlingStrategy":"validation","validationCode":"// Validate the pattern standalone before wiring into GsonBuilder\nstatic String validateDatePattern(String pattern) {\n if (pattern == null) return null; // reset\n try { new SimpleDateFormat(pattern); return pattern; }\n catch (IllegalArgumentException e) {\n throw new IllegalArgumentException(\"Bad date pattern: \" + pattern, e);\n }\n}\nnew GsonBuilder().setDateFormat(validateDatePattern(configPattern)).create();","typeGuard":"static boolean isValidDatePattern(String pattern) {\n if (pattern == null) return true;\n try { new SimpleDateFormat(pattern); return true; }\n catch (IllegalArgumentException e) { return false; }\n}","tryCatchPattern":null,"preventionTips":["Test patterns standalone with new SimpleDateFormat(pattern) before passing to GsonBuilder.","Quote literal text with single quotes (e.g. 'T', 'Z').","Pass null (not empty string) to reset to the default format.","Prefer java.time DateTimeFormatter patterns documentation if migrating, but remember Gson uses SimpleDateFormat syntax."],"tags":["gson-builder","date-format","configuration","simpledateformat","validation"],"analyzedSha":"8b8628c65699bc4421696183c62ae0c1b9b281dc","analyzedAt":"2026-08-04T19:12:22.202Z","schemaVersion":2}