failed to unmarshal the provided JSON - expects array of obj

Error message

failed to unmarshal the provided JSON - expects array of objects or just single object: %w

What it means

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.

Source

Thrown at core/fields_list.go:201

	// nothing to add
	if len(rawJSON) == 0 {
		return extractedFields, nil
	}

	// try to unmarshal first into a new fields list
	// (assuming that rawJSON is array of objects)
	err := json.Unmarshal(rawJSON, &extractedFields)
	if err != nil {
		// try again but wrap the rawJSON in []
		// (assuming that rawJSON is a single object)
		wrapped := make([]byte, 0, len(rawJSON)+2)
		wrapped = append(wrapped, '[')
		wrapped = append(wrapped, rawJSON...)
		wrapped = append(wrapped, ']')
		err = json.Unmarshal(wrapped, &extractedFields)
		if err != nil {
			return nil, fmt.Errorf("failed to unmarshal the provided JSON - expects array of objects or just single object: %w", err)
		}
	}

	return extractedFields, nil
}

func (l *FieldsList) add(pos int, newField Field) {
	fields := *l

	var replaceByName bool
	var replaceInPlace bool

	if pos < 0 {
		replaceInPlace = true
		pos = len(fields)
	} else if pos > len(fields) {
		pos = len(fields)
	}

View on GitHub (pinned to 5d217ddb50)

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.

Example fix

// before
"fields": {"type":"text","name":"title"} // single object with more than one field, or invalid entries

// after
"fields": [
  {"type": "text", "name": "title"}
]

Defensive patterns

Strategy: validation

Validate before calling

func validFieldsJSON(data []byte) error {
    var arr []json.RawMessage
    if err := json.Unmarshal(data, &arr); err != nil {
        // try single object
        wrapped := append(append([]byte{'['}, data...), ']')
        if err2 := json.Unmarshal(wrapped, &arr); err2 != nil {
            return fmt.Errorf("fields JSON is neither array nor single object")
        }
    }
    for _, raw := range arr {
        var t struct{ Type string `json:"type"` }
        if json.Unmarshal(raw, &t) != nil || t.Type == "" {
            return fmt.Errorf("field entry missing type: %s", raw)
        }
    }
    return nil
}

Try / catch

if err := collection.Fields.UnmarshalJSON(data); err != nil {
    if strings.Contains(err.Error(), "expects array of objects") {
        // restructure payload to [{...}] and report the offending JSON to the user
    }
}

Prevention

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": ...}.

When it happens

Trigger: 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).

Common situations: 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.

Related errors

AI-assisted analysis of pocketbase/pocketbase@5d217ddb50 (2026-08-15). Data as JSON: /api/errors/729e84c44fbf6dac. Report an issue: GitHub.