{"record":{"id":"729e84c44fbf6dac","repo":"pocketbase/pocketbase","slug":"failed-to-unmarshal-the-provided-json-expects-ar","errorCode":null,"errorMessage":"failed to unmarshal the provided JSON - expects array of objects or just single object: %w","messagePattern":"failed to unmarshal the provided JSON - expects array of objects or just single object: %w","errorType":"validation","errorClass":null,"httpStatus":400,"severity":"error","filePath":"core/fields_list.go","lineNumber":201,"sourceCode":"\n\t// nothing to add\n\tif len(rawJSON) == 0 {\n\t\treturn extractedFields, nil\n\t}\n\n\t// try to unmarshal first into a new fields list\n\t// (assuming that rawJSON is array of objects)\n\terr := json.Unmarshal(rawJSON, &extractedFields)\n\tif err != nil {\n\t\t// try again but wrap the rawJSON in []\n\t\t// (assuming that rawJSON is a single object)\n\t\twrapped := make([]byte, 0, len(rawJSON)+2)\n\t\twrapped = append(wrapped, '[')\n\t\twrapped = append(wrapped, rawJSON...)\n\t\twrapped = append(wrapped, ']')\n\t\terr = json.Unmarshal(wrapped, &extractedFields)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to unmarshal the provided JSON - expects array of objects or just single object: %w\", err)\n\t\t}\n\t}\n\n\treturn extractedFields, nil\n}\n\nfunc (l *FieldsList) add(pos int, newField Field) {\n\tfields := *l\n\n\tvar replaceByName bool\n\tvar replaceInPlace bool\n\n\tif pos < 0 {\n\t\treplaceInPlace = true\n\t\tpos = len(fields)\n\t} else if pos > len(fields) {\n\t\tpos = len(fields)\n\t}","sourceCodeStart":183,"sourceCodeEnd":219,"githubUrl":"https://github.com/pocketbase/pocketbase/blob/5d217ddb50cb144d80a5d0b0bdf11b52b2c3e457/core/fields_list.go#L183-L219","documentation":"Thrown when PocketBase tries to unmarshal a JSON payload into a FieldsList and both attempts fail: first as an array of field objects, then retrying with the payload wrapped in [ ] as a single object. This means the JSON is neither a valid array of field definitions nor a single valid field definition — the wrapped error is from the second (wrapped) json.Unmarshal attempt.","triggerScenarios":"Importing or loading a collection whose fields JSON is malformed: a JSON object with unknown keys at the array level, mixed array/scalar entries, invalid JSON syntax, or field objects missing the required \"type\" key (which fails in nested unmarshalling).","commonSituations":"Hand-writing collection import JSON; a field object whose type key was typo'd; copy-pasting fields from one collection export into another and breaking the array structure; API imports where the body was truncated.","solutions":["Validate the JSON parses (jq . file.json) and is an array of objects.","Ensure every element has a valid \"type\" (text, number, bool, email, url, editor, date, autodate, select, file, relation, json, geoPoint).","Compare against an export of a working collection to find the structural difference.","If importing via API, make sure the request body wasn't truncated or double-encoded."],"exampleFix":"// before\n\"fields\": {\"type\":\"text\",\"name\":\"title\"} // single object with more than one field, or invalid entries\n\n// after\n\"fields\": [\n  {\"type\": \"text\", \"name\": \"title\"}\n]","handlingStrategy":"validation","validationCode":"func validFieldsJSON(data []byte) error {\n    var arr []json.RawMessage\n    if err := json.Unmarshal(data, &arr); err != nil {\n        // try single object\n        wrapped := append(append([]byte{'['}, data...), ']')\n        if err2 := json.Unmarshal(wrapped, &arr); err2 != nil {\n            return fmt.Errorf(\"fields JSON is neither array nor single object\")\n        }\n    }\n    for _, raw := range arr {\n        var t struct{ Type string `json:\"type\"` }\n        if json.Unmarshal(raw, &t) != nil || t.Type == \"\" {\n            return fmt.Errorf(\"field entry missing type: %s\", raw)\n        }\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"if err := collection.Fields.UnmarshalJSON(data); err != nil {\n    if strings.Contains(err.Error(), \"expects array of objects\") {\n        // restructure payload to [{...}] and report the offending JSON to the user\n    }\n}","preventionTips":["Always export/import collections through PocketBase itself, not hand-edited JSON.","Lint imported JSON with jq before applying.","Keep every field object shaped {\"type\": ..., \"name\": ...}."],"tags":["json","fields","import","collections"],"backgroundTag":null,"analyzedSha":"5d217ddb50cb144d80a5d0b0bdf11b52b2c3e457","analyzedAt":"2026-08-15T10:06:33.165Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}