Running a successful upload into Salesforce is a six-step routine: pick the right tool, prepare the file with clean data, validate the source against the target schema, run a test load against a sandbox first, run the production load with monitoring, and process the error file. The order matters. Most upload failures come from skipping the validation step and discovering the data issues only at production load time. Build the routine into a runbook and follow it every time, regardless of whether the load is one-off historical migration or a nightly sync.
- Pick the right tool for the volume and the operator
Match the tool to the load characteristics. Data Import Wizard for standard objects under 50,000 records run by a non-technical user. Data Loader for any object up to 5 million records run by an admin or developer comfortable with the desktop UI. Bulk API or Bulk API 2.0 for programmatic loads from an integration pipeline. Third-party tools for scheduled syncs or multi-system orchestration. Picking too lightweight a tool forces a redo when volume grows; picking too heavyweight a tool wastes setup effort on a one-off load. Document the choice in the runbook so future operators know which tool to reach for.
- Prepare and validate the source file
Open the CSV in a text editor (not Excel, which silently mangles long numbers and dates) and confirm the encoding is UTF-8 without BOM. Confirm every column matches a Salesforce field by API name. Confirm date and DateTime values are in the expected format. Confirm picklist values match the org definitions exactly (case-sensitive). Confirm lookup field values reference real Salesforce record IDs or external IDs that exist. Run a small sample (10 to 100 rows) through Data Loader against a sandbox; the success file should match the input row count. If the sample fails, fix the file before proceeding.
- Run a sandbox test load and review results
From Data Loader (or the chosen tool), connect to a sandbox refreshed from production. Load the full file or a representative sample (10 to 25 percent for very large files). Review the success and error CSVs. Open Salesforce and spot-check the loaded records: are field values correct, are lookups linked properly, did validation rules fire as expected, did triggers run without governor-limit errors. If anything is wrong, fix the file and run again. Do not move to production until the sandbox load is clean. This is the single step that saves the most pain across the lifecycle of the upload.
- Run the production load and process errors
Run the upload against production with the same configuration that worked in sandbox. Monitor the job log for progress. After the job completes, immediately review the error CSV. Fix the source data for any failed records and run a corrective load that includes only the failed records. Iterate until the error file is empty. Document the final record counts (inserted, updated, errored) in the upload log along with the date, the operator, and any noteworthy issues. For recurring uploads, automate the error notification: if more than N records fail, email the runbook owner.
- Excel silently mangles long numbers (turns 18-character Salesforce IDs into scientific notation) and dates (reformats to local locale). Open CSVs in a text editor or in a dedicated CSV tool, never in Excel for upload preparation.
- Picklist values must match the org definitions exactly, case-sensitive. Inconsistent spellings (Hot vs hot vs HOT) are the most common reason records fail with INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST.
- Apex triggers, validation rules, and sharing rules all fire on uploaded records. Large loads can hit governor limits if the triggers are not bulk-safe; disable non-essential triggers or run loads off-peak.
- Bulk API counts against the daily API request limit but uses fewer calls than equivalent REST loads. Watch the daily usage gauge if the upload is part of a larger integration pipeline; one runaway load can starve the rest of the day.
- Upsert requires an External ID field defined as such in the schema. Without it, Data Loader rejects the upsert operation. Confirm the field flag is set before scoping a recurring sync that relies on upsert.