{"record":{"id":"2b095300530fccce","repo":"dgraph-io/dgraph","slug":"initial-element-not-found-in-json","errorCode":null,"errorMessage":"initial element not found in json","messagePattern":"initial element not found in json","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"chunker/json_parser.go","lineNumber":743,"sourceCode":"\t\t\tif len(a) > 0 {\n\t\t\t\t// attempt to convert each array element to a\n\t\t\t\t// map[string]interface{} for further parsing\n\t\t\t\tvar o interface{}\n\t\t\t\tfor _, o = range a {\n\t\t\t\t\tif _, ok := o.(map[string]interface{}); !ok {\n\t\t\t\t\t\treturn errors.New(\"only array of map allowed at root\")\n\t\t\t\t\t}\n\t\t\t\t\t// pass to next parsing stage\n\t\t\t\t\tmr, err := buf.mapToNquads(o.(map[string]interface{}), op, \"\")\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\treturn err\n\t\t\t\t\t}\n\t\t\t\t\tbuf.checkForDeletion(mr, o.(map[string]interface{}), op)\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\tdefault:\n\t\treturn errors.New(\"initial element not found in json\")\n\t}\n\treturn nil\n}\n\n// ParseJSON parses the given byte slice and pushes the parsed NQuads into the buffer.\nfunc (buf *NQuadBuffer) ParseJSON(b []byte, op int) error {\n\tbuffer := bytes.NewBuffer(b)\n\tdec := json.NewDecoder(buffer)\n\tdec.UseNumber()\n\tms := make(map[string]interface{})\n\tvar list []interface{}\n\tif err := dec.Decode(&ms); err != nil {\n\t\t// Couldn't parse as map, lets try to parse it as a list.\n\t\tbuffer.Reset() // The previous contents are used. Reset here.\n\t\t// Rewrite b into buffer, so it can be consumed.\n\t\tif _, err := buffer.Write(b); err != nil {\n\t\t\treturn err\n\t\t}","sourceCodeStart":725,"sourceCodeEnd":761,"githubUrl":"https://github.com/dgraph-io/dgraph/blob/759e242be62c91f8d084da06ad0c8d21256d9c07/chunker/json_parser.go#L725-L761","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\n{\"name\": \"alice\"}\n// after\n[{\"name\": \"alice\"}]","handlingStrategy":"validation","validationCode":"func checkRootArray(b []byte) error {\n\tvar v interface{}\n\tif err := json.Unmarshal(b, &v); err != nil {\n\t\treturn err\n\t}\n\tif _, ok := v.([]interface{}); !ok {\n\t\treturn errors.New(\"root must be a JSON array\")\n\t}\n\treturn nil\n}","typeGuard":"func isArrayRoot(b []byte) bool {\n\tvar v interface{}\n\tif json.Unmarshal(b, &v) != nil {\n\t\treturn false\n\t}\n\t_, ok := v.([]interface{})\n\treturn ok\n}","tryCatchPattern":"if err := buf.FastParseJSON(b, op); err != nil && strings.Contains(err.Error(), \"initial element not found in json\") {\n\t// fall back to ParseJSON or wrap the object in an array\n}","preventionTips":["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"],"tags":["json-parser","input-validation","root-element","dgraph"],"backgroundTag":"invalid-json-root-structure","analyzedSha":"759e242be62c91f8d084da06ad0c8d21256d9c07","analyzedAt":"2026-09-01T14:42:12.034Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}