Failed to load batch — InvalidBatch: invalid CSV header / unrecognized field

Bulk API 2.0 takes a CSV upload, matches each column header to a field on the target sObject, and writes the values. The header is the contract. If a header doesn't match a field, the platform rejects the batch.

Common CSV mistakes

1. Wrong field API name

Name,Email,Industry
Acme,acme@example.com,Tech

If the object's email field is Email__c (custom) but you wrote Email (which doesn't exist on that object), the load fails. Fix: use the exact API name:

Name,Email__c,Industry

2. Case mismatch

Field API names are case-insensitive in many Salesforce contexts but the Bulk API is case-sensitive:

name,email,industry   <-- ❌ Bulk API expects 'Name', 'Email', 'Industry'

Use the field's exact case as defined in Setup → Object → Fields.

3. Including formula or roll-up fields

Name,Total_Children__c,Industry

If Total_Children__c is a formula, the Bulk API rejects it as non-writeable. Drop derived fields from the CSV; the platform recomputes them after the load.

4. Including system-managed fields

Id, CreatedDate, IsDeleted etc. — the Bulk API allows Id for updates only, and rejects most other system fields:

Id,Name,CreatedDate    <-- ❌ CreatedDate is system-managed

For insert: omit Id. For update: include Id, omit other system fields.

For upsert: include the External ID field instead of Id:

External_Id__c,Name,Email

5. Encoding mismatch

Bulk API expects UTF-8. If your CSV is UTF-16 with a BOM, or Latin-1, the parser sees garbled headers and fails on row 1. Always save as UTF-8 (no BOM) before upload.

Diagnose

The Bulk API job result includes per-row failure reasons:

sf data resume --job-id 750xxx --target-org production
# Or:
sf data import bulk --file accounts.csv --sobject Account --target-org production --wait 10

The failed-rows CSV has a sf__Error column with the reason for each row. Group by sf__Error to see which header is the culprit.

A subtler case: relationship fields

To set a lookup field by external ID:

Name,Account__r.External_Id__c
Smith Project,CRM-001

The header uses dot notation: <RelationshipName>.<ExternalIdField>. Note __r for custom relationships, no __c. If you write Account__c with the parent's external ID, the Bulk API treats it as the lookup ID itself and rejects.

When the upload IS valid but rows fail

If the headers match but individual rows fail, the row-level error is in sf__Error:

• REQUIRED_FIELD_MISSING — see that page
• INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST — see that page
• STRING_TOO_LONG — see that page

Each row is independent in Bulk API 2.0 — failed rows don't roll back successful ones. So you can clean and re-submit just the failed rows.