Salesforce Data Loader: Install, Import, Export, Fix Errors

Key takeaways

• Salesforce Data Loader is Salesforce's client application for bulk insert, update, upsert, delete and export of records using CSV files.
• Most Data Loader failures come from the file or from your org's automation, not from the tool, so prepare the CSV and run a small pilot first.
• Data Loader writes a success file and an error file on every run, and the error file's reason column tells you exactly what to fix.
• Batch size and Bulk API settings are the two levers that fix most locking and governor-limit errors.

A 200,000-row load fails at row 199,800 because one lookup ID has a space in it. I've seen versions of that story more often than any other in data work, and it's almost never the tool's fault.

This is my reference guide to Salesforce Data Loader for admins: how to install it, run imports and exports, and fix the errors you'll really hit. My argument is simple. Data Loader is a thin, honest tool. It does what your file and your org's automation allow, so your job is to control those two things before you click Finish.

What Salesforce Data Loader is, and when the Import Wizard is enough

Data Loader is a client application you install on your computer to bulk import or export Salesforce records, and you reach for it when the in-browser tools run out of road.

According to the Data Loader Guide, it reads CSV files (or a database connection) when importing, and writes CSV files when exporting. It supports insert, update, upsert, delete, hard delete and export.

The Data Import Wizard inside Setup is simpler and fine for small, common-object jobs. I move to Data Loader when any of these is true:

• The file is large.
• I need to export, not just import.
• I need to delete in bulk.
• I want to upsert on an external ID.
• I need a repeatable job.

The guide's "When to Use Data Loader" page has the current volume guidance, so check it rather than trusting a number from a blog, including this one.

How to install Salesforce Data Loader

Download it only from Salesforce's official page, check the Java prerequisite, and keep it current, because Salesforce doesn't support older versions.

1. Go to the official Salesforce Data Loader download page. It offers builds for Windows and macOS.
2. Read the Install Data Loader page for the current prerequisites and installation considerations, including the Java runtime your version needs.
3. Install, launch, and choose an operation.

Command-line and batch mode are Windows only, per the same guide. Mac users doing scheduled loads will need another route.

Two admin notes. Your user needs API Enabled on the profile or a permission set, plus object and field permissions for whatever you're loading.

My take: Install Data Loader, but connect it to a sandbox first, every time. Production is where you go once the pilot has passed. I'd rather lose twenty minutes than explain a mass update to a sales director. If you aren't sure which sandbox to pick, see Salesforce sandbox types.

How to prepare your CSV for Salesforce Data Loader

Many load errors are decided before the wizard opens, in the spreadsheet.

My checklist:

• Save as CSV UTF-8. Accented names turn into garbage otherwise.
• Use IDs, not names, for lookups. AccountId needs a record ID, not "Acme Ltd". For updates, the file needs the record Id column.
• Protect your IDs. Excel can mangle long numbers and strip leading zeros from codes and phone numbers. Format those columns as text before pasting.
• Trim whitespace. A trailing space in a picklist value or ID causes a rejection that looks fine on screen.
• Match picklists exactly, especially restricted ones.
• Check field lengths against the target field.
• Use ISO-style dates (2026-11-30) where you can, so regional formats don't bite.
• Load parents before children. Accounts first, then Contacts, then Opportunities.

Before any update or delete, export the same records with their IDs. That file is your rollback.

How to import records with Data Loader: insert, update and upsert

Pick the operation that matches your file: insert for new records, update for existing ones with IDs, and upsert when you don't know which is which.

Per the Insert, Update, or Delete Data guide, upsert combines both. If a record in your file matches an existing one, it's updated. If there's no match, a new record is created.

The steps are the same for all three:

1. Open Data Loader and choose Insert, Update or Upsert.
2. Log in and select your org.
3. Choose the object (tick "Show all objects" for custom or less common ones).
4. Select your CSV file.
5. For upsert, choose the matching field: the record Id or an external ID field.
6. Use Create or Edit a Map to map columns to fields. Auto-match works until your headers differ from field API names. Save the mapping as an .sdl file if you'll reuse it.
7. Choose a folder for the result files and click Finish.

Data Loader writes two CSVs, one starting success and one starting error. The success file lists loaded rows with new record IDs. The error file lists rejected rows with a column explaining why. That column is your debugging tool.

My upsert advice: create a dedicated external ID field for each major source system. Matching on a unique, indexed external ID makes re-runs safe, so you can fix the error rows and reload without creating duplicates.

My take: Always run a pilot of 20 to 50 rows, including the ugliest rows you can find, before the full load. A clean pilot proves the mapping. It doesn't prove the data. Pick rows with blanks, long text and odd characters on purpose.

How to export data from Salesforce with Data Loader

An export is just a SOQL query that writes to a CSV, so build it carefully and select only the fields you need.

1. Choose Export (or Export All, which also includes deleted records still in the Recycle Bin).
2. Log in, select the object and choose the target CSV file.
3. Pick the fields in the query builder and add a WHERE clause.
4. Click Finish.

A typical query:

SELECT Id, Name, Industry, OwnerId
FROM Account
WHERE CreatedDate = LAST_N_DAYS:30

Two habits help here. Always include Id, so the file can double as an update template or backup. And filter exports when you can, because a full-table export of a big object is slow and rarely what you need. For a quick look at a few records, a browser tool is quicker; I cover options in Salesforce Inspector Reloaded and Workbench and alternatives.

How to delete records safely with Data Loader

Treat Delete like a production deployment: back up first, pilot, then run.

Standard Delete sends records to the Recycle Bin, where you can restore them for a limited time. Hard delete skips the Recycle Bin. The official guide states that hard-deleted records aren't stored in the Recycle Bin and are eligible for deletion.

My rule is not to hard delete unless you have an export of exactly those IDs and a second person has looked at the file.

Common Salesforce Data Loader errors and how to fix them

Read the error column first: Salesforce returns a status code, and each code points to a specific cause.

Salesforce publishes its own common Data Loader error messages article. These are the ones I see admins hit most:

Error code or message	Usual cause	Fix
REQUIRED_FIELD_MISSING	A required field is blank or its column isn't mapped	Map and fill the field (Last Name on Contact is a classic)
INVALID_FIELD_FOR_INSERT_UPDATE	Field is read-only (formula, auto-number) or the user lacks field-level security	Remove the column, or grant edit access on the field
INVALID_CROSS_REFERENCE_KEY	A lookup ID doesn't exist, belongs to another object, or isn't visible to the user	Verify the IDs and load parent records first
MALFORMED_ID	ID isn't a valid 15 or 18-character Salesforce ID, often Excel damage or stray spaces	Re-pull IDs from an export and trim the column
STRING_TOO_LONG	Text exceeds the field length	Shorten the data or increase the field length
INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST	Value isn't in a restricted picklist	Match the value exactly, or add it to the picklist
DUPLICATES_DETECTED	A duplicate rule blocked the save	De-duplicate the file; change the rule only as a deliberate admin decision
FIELD_CUSTOM_VALIDATION_EXCEPTION	A validation rule fired	Read the rule's message and fix the data
UNABLE_TO_LOCK_ROW	Parallel batches updating records that share a parent	Sort by parent, lower the batch size, or use serial mode
Too many SOQL queries: 101 or CPU time limit	A trigger or flow isn't bulk-safe	Reduce batch size now, fix the automation properly

My reading is that it's a mismatch between your file and what Data Loader expects to find in it, such as a mapped column missing from the CSV. Confirm against the article's stated cause before you change anything.

The 101 and CPU errors aren't really Data Loader errors. They mean your org's automation can't handle a batch. Data Loader hands records over in batches, and a trigger or flow that works for one record can break at a whole batch. If that's your problem, read Governor Limits in Salesforce and write a bulk-safe trigger. To trace the automation itself, try How to debug a Salesforce Flow.

Data Loader settings that fix most errors: batch size, Bulk API and serial mode

Three settings do most of the work: batch size, Bulk API and serial mode, plus the null-values option.

Open Settings in Data Loader and look at these:

• Batch size. The standard API default is commonly 200 records (check your version). Dropping it reduces how much automation runs in one transaction. It's the quickest stopgap for limit errors.
• Use Bulk API. Better throughput for large volumes and required for hard delete.
• Enable serial mode for Bulk API. Batches run one after another instead of in parallel. It's slower, but it often clears UNABLE_TO_LOCK_ROW.
• Insert null values. By default, blank cells in your CSV leave the existing value alone. If you actually want to blank a field, turn this on (it only works with the standard SOAP API, and you should turn it off again afterwards). If you use Bulk API or Bulk API 2.0 the option isn't available and empty cells are ignored on update, so put #N/A in the CSV cell instead.

The last one is the setting that causes silent problems. People expect empty cells to clear data, nothing happens, and they assume the load failed.

My take: Lowering the batch size is a plaster, not a cure. If a load only works at batch size 1, your automation has a bulk-safety bug, and your users will hit it eventually through integrations and other bulk edits. Fix the trigger or flow.

Data Loader practice plan for this week

Try this week:

• Install the latest Data Loader from the official page and connect it to a sandbox.
• Export 50 Accounts with Id, change one field in the CSV, and run an Update. Open both result files.
• Create an external ID field on one object and practise an upsert with a 20-row file.
• Pick your most-used object and test what happens at batch size 200 versus 20.

If you want help designing a clean migration or an integration that loads data safely, get in touch.

Frequently asked questions

Is Salesforce Data Loader free?

Yes. Salesforce provides Data Loader as a client application, available from its developer tools page. Your org's edition and API access determine whether you can use it. API usage still counts against your org's limits.

What is the difference between Data Loader and the Data Import Wizard?

The Data Import Wizard runs in your browser and suits smaller jobs on common objects. Data Loader is a desktop application that handles larger volumes, exports, deletes, upserts on external IDs and saved mappings. If you need to export or delete, Data Loader is the one.

How do I fix "INVALID_CROSS_REFERENCE_KEY" in Data Loader?

It means a lookup or master-detail ID in your file doesn't point to a valid, visible record. Check the ID belongs to the right object, exists in the target org (sandbox IDs differ from production), and that the parent was loaded first. Then re-run only the rows from the error file.

Can I undo a Data Loader load?

Not with a button. Inserted records can be deleted using the IDs in your success file. Updated or deleted records need your pre-load export, so back up first. Hard-deleted records skip the Recycle Bin, as the official guide notes.

Why does Data Loader say some rows failed when the rest loaded?

Data Loader processes records in batches and reports row-level results. Good rows are saved and bad rows are rejected, with the reason in the error CSV. Fix those rows and load the error file's data again, rather than the whole original file.