{"record":{"id":"70e6afde6b058e76","repo":"payloadcms/payload","slug":"json-import-data-must-be-an-array-of-documents","errorCode":null,"errorMessage":"JSON import data must be an array of documents","messagePattern":"JSON import data must be an array of documents","errorType":"validation","errorClass":"APIError","httpStatus":500,"severity":"error","filePath":"packages/plugin-import-export/src/utilities/parseJSON.ts","lineNumber":20,"sourceCode":"\nimport { APIError } from 'payload'\n\nexport type ParseJSONArgs = {\n  data: Buffer | string\n  req: PayloadRequest\n}\n\n/**\n * Parses JSON data into an array of record objects.\n * Validates that the input is an array of documents.\n */\nexport const parseJSON = ({ data, req }: ParseJSONArgs): Record<string, unknown>[] => {\n  try {\n    const content = typeof data === 'string' ? data : data.toString('utf-8')\n    const parsed = JSON.parse(content)\n\n    if (!Array.isArray(parsed)) {\n      throw new APIError('JSON import data must be an array of documents')\n    }\n\n    return parsed\n  } catch (err) {\n    req.payload.logger.error({ err, msg: 'Error parsing JSON' })\n    if (err instanceof APIError) {\n      throw err\n    }\n    throw new APIError('Invalid JSON format')\n  }\n}\n","sourceCodeStart":2,"sourceCodeEnd":32,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/plugin-import-export/src/utilities/parseJSON.ts#L2-L32","documentation":"parseJSON requires the top-level JSON value to be an array of documents. If JSON.parse succeeds but yields a non-array (object, primitive, string), it throws an APIError. The importer processes rows, so a single object or a wrapper object is rejected.","triggerScenarios":"The JSON file is a single object {} instead of [{}]; the data is wrapped like { data: [...] }; the file contains a bare string/number.","commonSituations":"User exports a single record then tries to re-import it; a wrapper-shaped API response saved as a file; confusion between 'one object' and 'array of objects'.","solutions":["Wrap a single object in an array before importing.","If the file is { data: [...] }, extract the array and re-save.","Validate the parsed shape is an array before invoking import."],"exampleFix":"// before: file content = {\"title\":\"a\"}\n// after: file content = [{\"title\":\"a\"}]","handlingStrategy":"validation","validationCode":"const parsed = JSON.parse(content)\nif (!Array.isArray(parsed)) {\n  // wrap or reject before import\n  throw new Error('JSON must be an array of documents')\n}","typeGuard":"const isArrayOfObjects = (v: unknown): v is Record<string, unknown>[] =>\n  Array.isArray(v) && v.every((item) => item !== null && typeof item === 'object')","tryCatchPattern":null,"preventionTips":["Always export as an array, even for a single record.","If your source is { data: [...] }, extract the array first.","Validate the top-level shape before queuing an import."],"tags":["import","json","validation","plugin-import-export"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}