payloadcms/payload · error · APIError

Invalid JSON format

Error message

Invalid JSON format

What it means

parseJSON wraps JSON.parse in try/catch. If parsing throws a SyntaxError (and it isn't an APIError), it logs the error and rethrows as APIError 'Invalid JSON format'. The bytes were not valid JSON.

Source

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

 * 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. Validate the content parses with JSON.parse before import and show the parse error.
2. Confirm the format field matches the actual file content.
3. Re-encode the file as UTF-8 without BOM if needed.

let content: string
try {
  content = typeof data === 'string' ? data : data.toString('utf-8')
  JSON.parse(content) // pre-validate, surface real syntax error
} catch (e) {
  throw new Error(`Source is not valid JSON: ${(e as Error).message}`)
}

try {
  await createImport({ ..., format: 'json' })
} catch (err) {
  if (err instanceof APIError && /Invalid JSON format/.test(err.message)) {
    // tell the user the file isn't valid JSON or format is wrong
  } else throw err
}

When it happens

Trigger: Malformed JSON: trailing comma, unquoted keys, BOM, truncated file, or a non-JSON file (e.g. CSV) fed in with format='json'.

Common situations: format field mismatch (CSV content sent as json); encoding issues (UTF-16/BOM); hand-edited file with a syntax error; truncated upload.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• JSON import data must be an array of documents
• 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/ae204d53f5ed0181. Report an issue: GitHub.