payloadcms/payload · error · APIError

Import file contains ${documents.length} documents but limit

Error message

Import file contains ${documents.length} documents but limit is ${maxLimit}

What it means

After parsing, createImport enforces an upper bound on document count via the resolved maxLimit (from plugin importLimit). If documents.length exceeds maxLimit it throws 400 before processing, deliberately to save memory and time on oversized imports.

Source

Thrown at packages/plugin-import-export/src/import/createImport.ts:197

      }),
    )
  }

  if (debug) {
    req.payload.logger.debug({
      msg: `Parsed ${documents.length} documents from ${format} file`,
    })
    if (documents.length > 0) {
      req.payload.logger.debug({
        doc: documents[0],
        msg: 'First document sample:',
      })
    }
  }

  // Enforce maxLimit before processing to save memory/time
  if (typeof maxLimit === 'number' && maxLimit > 0 && documents.length > maxLimit) {
    throw new APIError(
      `Import file contains ${documents.length} documents but limit is ${maxLimit}`,
      400,
      null,
      true,
    )
  }

  // Remove disabled fields from all documents
  if (disabledFields.length > 0) {
    documents = documents.map((doc) => removeDisabledFields(doc, disabledFields))
  }

  if (debug) {
    req.payload.logger.debug({
      batchSize,
      documentCount: documents.length,
      msg: 'Processing import in batches',
    })

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Raise importLimit in the plugin-import-export config for the collection/global.
2. Split the source file into chunks under maxLimit and import each separately.
3. Pre-filter rows in the source so the parsed count stays under the limit.

Example fix

// before: importLimit too low
importExportPlugin({ collections: { posts: { importLimit: 100 } } })
// after
importExportPlugin({ collections: { posts: { importLimit: 10000 } } })

function chunkDocuments<T>(docs: T[], maxLimit: number): T[][] {
  if (docs.length > maxLimit) {
    // split instead of failing
  }
  const chunks: T[][] = []
  for (let i = 0; i < docs.length; i += maxLimit) chunks.push(docs.slice(i, i + maxLimit))
  return chunks
}

// parse once, then import each chunk under the limit

try {
  await createImport({ ..., maxLimit })
} catch (err) {
  if (err instanceof APIError && /limit is/.test(err.message)) {
    // split the source file and retry each chunk
  } else throw err
}

When it happens

Trigger: Uploading a CSV/JSON with more rows/documents than the configured importLimit. maxLimit is a positive number resolved from the plugin config and passed into createImport.

Common situations: importLimit left at a low default while real files have thousands of rows; a one-off bulk import exceeds the steady-state cap; limit lowered without communicating to data owners.

Related errors

• No file data provided for import
• Collection with slug ${collectionSlug} not found
• Import document not found: ${importId}
• Collection config not found for: ${importCollection}
• Unable to determine mimetype for file: ${importDoc.filename}

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