json: cannot unmarshal array into Go value of type map[string]string: what it means and how to fix it

What the error means

json: cannot unmarshal array into Go value of type map[string]string 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 (go)

// 1) Decode into interface{} / map first to inspect real types
var any interface{}
if err := json.Unmarshal(body, &any); err != nil {
    return err
}

// 2) Inspect suspicious keys/fields (example)
m, _ := any.(map[string]interface{})
for k := range m {
    fmt.Println("key:", k)
    break // print a few keys first
}

// 3) Only then unmarshal into a strong type
// var dto MyDto
// dec := json.NewDecoder(bytes.NewReader(body))
// dec.DisallowUnknownFields() // if you want strict schema
// if err := dec.Decode(&dto); err != nil { return err }

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.