Why Fastjson’s Date Formatting Breaks on Linux and How to Resolve It

Date format priority issue

When migrating a Spring Boot project from Gson to Fastjson, a global date format yyyy-MM-dd HH:mmss was configured. A bean field annotated with @JSONField(format="yyyy-MM-dd") produced correct output on Windows but included time on Linux.

Root cause: the test environment used Fastjson 1.2.53, which had a bug where field‑level format was ignored if a global pattern was set. The bug is tracked to issue #1868 and was fixed in Fastjson 1.2.72 (PR #2706).

Solution: upgrade the Fastjson dependency to version 1.2.72 or newer.

$ref circular reference issue

Fastjson serializes objects that appear multiple times as a JSON reference using the $ref syntax. Example method returns a map with two lists ( young and children) that share the same Person instances. The generated JSON contains:

{
  "code":"200",
  "message":"成功!",
  "result":{
    "young":[{"age":23,"name":"Li Si"},{"age":17,"name":"Wang Ma Zi"}],
    "children":[{"$ref":"$.result.young[1]"}]
  }
}

Fastjson treats the second occurrence as a circular reference and replaces it with a $ref pointer. The default feature SerializerFeature.DisableCircularReferenceDetect is disabled, so circular‑reference detection is enabled.

Fixes:

Disable the detection globally, e.g.

JSON.DEFAULT_GENERATE_FEATURE |= SerializerFeature.DisableCircularReferenceDetect.getMask();

or configure the FastJsonHttpMessageConverter with SerializerFeature.DisableCircularReferenceDetect.

Upgrade to Fastjson 2, where the behavior can be configured per serializer.

Other relevant serializer features

SerializerFeature.WriteMapNullValue

– by default Fastjson omits fields whose value is null. Enable this feature to include them. SerializerFeature.WriteNullListAsEmpty – serializes a null list as [] instead of null.

Takeaways

Version mismatches can cause environment‑specific bugs; always verify the Fastjson version in all deployment artifacts.

When unexpected serialization occurs, search the Fastjson GitHub issue tracker; many bugs are already documented (e.g., https://github.com/alibaba/fastjson/issues/1868, https://github.com/alibaba/fastjson/pull/2706, https://github.com/alibaba/fastjson/issues/3643).

Control serializer features explicitly rather than relying on defaults, especially for circular‑reference detection and null handling.