payloadcms/payload · error · APIError

JSON import data must be an array of documents

Error message

JSON import data must be an array of documents

What it means

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.

Source

Thrown at packages/plugin-import-export/src/utilities/parseJSON.ts:20

import { APIError } from 'payload'

export type ParseJSONArgs = {
  data: Buffer | string
  req: PayloadRequest
}

/**
 * Parses JSON data into an array of record objects.
 * Validates that the input is an array of documents.
 */
export const parseJSON = ({ data, req }: ParseJSONArgs): Record<string, unknown>[] => {
  try {
    const content = typeof data === 'string' ? data : data.toString('utf-8')
    const parsed = JSON.parse(content)

    if (!Array.isArray(parsed)) {
      throw new APIError('JSON import data must be an array of documents')
    }

    return parsed
  } catch (err) {
    req.payload.logger.error({ err, msg: 'Error parsing JSON' })
    if (err instanceof APIError) {
      throw err
    }
    throw new APIError('Invalid JSON format')
  }
}

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Wrap a single object in an array before importing.
2. If the file is { data: [...] }, extract the array and re-save.
3. Validate the parsed shape is an array before invoking import.

Example fix

// before: file content = {"title":"a"}
// after: file content = [{"title":"a"}]

const parsed = JSON.parse(content)
if (!Array.isArray(parsed)) {
  // wrap or reject before import
  throw new Error('JSON must be an array of documents')
}

const isArrayOfObjects = (v: unknown): v is Record<string, unknown>[] =>
  Array.isArray(v) && v.every((item) => item !== null && typeof item === 'object')

When it happens

Trigger: The JSON file is a single object {} instead of [{}]; the data is wrapped like { data: [...] }; the file contains a bare string/number.

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

Related errors

• Invalid JSON format
• No file data provided for import
• ${value} is not allowed as a JSON query value
• ${value} is not allowed as a JSON query value
• JSONObject cannot represent non-object value: ${value}

AI-assisted analysis of payloadcms/payload@00c58b35c0 (2026-08-12). Data as JSON: /api/errors/70e6afde6b058e76. Report an issue: GitHub.