What causes "initial element not found in json" in dgraph-io/dgraph?

Wrap the single object in an array: [{ ... }].

initial element not found in json

Error message

initial element not found in json

What it means

FastParseJSON (chunker/json_parser.go:743) switches on the type of the decoded root value; only arrays are supported at the root. Any other root type (map, string, number, bool) reaches the default branch and yields this error, meaning the parser could not find the expected initial array element to begin parsing.

Source

Thrown at chunker/json_parser.go:743

			if len(a) > 0 {
				// attempt to convert each array element to a
				// map[string]interface{} for further parsing
				var o interface{}
				for _, o = range a {
					if _, ok := o.(map[string]interface{}); !ok {
						return errors.New("only array of map allowed at root")
					}
					// pass to next parsing stage
					mr, err := buf.mapToNquads(o.(map[string]interface{}), op, "")
					if err != nil {
						return err
					}
					buf.checkForDeletion(mr, o.(map[string]interface{}), op)
				}
			}
		}
	default:
		return errors.New("initial element not found in json")
	}
	return nil
}

// ParseJSON parses the given byte slice and pushes the parsed NQuads into the buffer.
func (buf *NQuadBuffer) ParseJSON(b []byte, op int) error {
	buffer := bytes.NewBuffer(b)
	dec := json.NewDecoder(buffer)
	dec.UseNumber()
	ms := make(map[string]interface{})
	var list []interface{}
	if err := dec.Decode(&ms); err != nil {
		// Couldn't parse as map, lets try to parse it as a list.
		buffer.Reset() // The previous contents are used. Reset here.
		// Rewrite b into buffer, so it can be consumed.
		if _, err := buffer.Write(b); err != nil {
			return err
		}

View on GitHub (pinned to 759e242be6)

Solutions

Wrap the single object in an array: [{ ... }].
Use ParseJSON, which accepts object roots, if your input is a single map.
Verify the file is complete and starts with '[' — truncated JSON may decode to a non-array.

Example fix

// before
{"name": "alice"}
// after
[{"name": "alice"}]

Defensive patterns

Strategy: validation

Validate before calling

func checkRootArray(b []byte) error {
	var v interface{}
	if err := json.Unmarshal(b, &v); err != nil {
		return err
	}
	if _, ok := v.([]interface{}); !ok {
		return errors.New("root must be a JSON array")
	}
	return nil
}

Type guard

func isArrayRoot(b []byte) bool {
	var v interface{}
	if json.Unmarshal(b, &v) != nil {
		return false
	}
	_, ok := v.([]interface{})
	return ok
}

Try / catch

if err := buf.FastParseJSON(b, op); err != nil && strings.Contains(err.Error(), "initial element not found in json") {
	// fall back to ParseJSON or wrap the object in an array
}

Prevention

FastParseJSON only accepts a top-level JSON array — check before calling
Use ParseJSON for single-object payloads
Guard against truncated files that fail to decode as arrays

When it happens

Trigger: Calling FastParseJSON with JSON whose root is an object ({...}), a bare scalar, or an unmarshal result that is not a []interface{} — e.g. passing a single record instead of an array of records.

Common situations: Users converting from a tool that emits a single JSON object per file (e.g. one document exports), or passing truncated/old format files to the fast path.

Related errors

AI-assisted analysis of dgraph-io/dgraph@759e242be6 (2026-09-01). Data as JSON: /api/errors/2b095300530fccce. Report an issue: GitHub.