Cannot deserialize instance of `java.util.LinkedHashMap` out of START_ARRAY token: what it means and how to fix it

What the error means

Cannot deserialize instance of `java.util.LinkedHashMap` out of START_ARRAY token usually means the JSON was parsed, but the value at some path does not match the type/schema your code expects (for example: array vs object, number vs string, null vs non-nullable).

Most common real-world causes

• Your code expects a different type (number vs string, bool vs string, object vs array).
• A field is null/missing but your type is non-nullable (or your code assumes it is always present).
• The API response shape changed (or differs by environment / feature flags).
• You are deserializing the wrong endpoint or the response is an error payload with a different schema.
• Date/UUID/IP formats don't match what the deserializer expects.

Fast debugging steps

• Parse into a generic JSON type first (Value/JToken/JsonElement/JsonNode) and inspect the actual shape at the failing path.
• Confirm whether the field is an array vs object and whether scalars are strings vs numbers.
• Add defensive handling for null/missing fields (optional types, defaults, or custom converters).
• Log the raw response (or a redacted sample) and validate it locally to rule out truncation or hidden prefixes.
• Update DTO/types to match the real response shape (or use a more flexible model for unstable fields).

Code example (java)

// Parse into JsonNode first to inspect shape/type mismatches
ObjectMapper mapper = new ObjectMapper();
JsonNode node = mapper.readTree(body);

// Example checks
JsonNode value = node.get("value");
if (value != null) {
  System.out.println(value.getNodeType());
  System.out.println(value.toString());
}

// Then deserialize into your DTO once the schema matches
// MyDto dto = mapper.treeToValue(node, MyDto.class);

Fix without uploading data

If the JSON contains sensitive data, validate and fix it locally. No Upload Tools runs 100% in your browser.

• JSON Validator to pinpoint the exact syntax error.
• JSON Repair to remove comments/trailing commas when the source is not strict.
• JSON Formatter to pretty-print and inspect structure.
• JSON String Escape if the issue is inside a string (newlines/tabs/quotes).

Workflow: validate -> fix the first error -> validate again -> export/convert.

FAQ

Does this mean the JSON is invalid? Not necessarily. Many of these errors happen when the JSON is valid, but your code expects a different type/shape.

What is the fastest fix? Parse into a generic JSON type first (Value/JToken/JsonElement/JsonNode), inspect the failing path, then update your DTO/type (or add a converter) to match the real response.