CSV Imports: Why They Fail and How to Fix It

A Practical Guide to Troubleshooting NetSuite CSV Import Errors

customer-import.csv
184 rows ready for validation
UTF-8

Overview

Stop Guessing, Start Fixing

CSV imports are one of the most common ways to get data into NetSuite — whether you are migrating from another system, loading a bulk update, or bringing in data from a third-party source. They are also one of the most common sources of frustration. A single formatting error, a mismatched field name, or an encoding issue can reject an entire file with an error message that tells you very little about what actually went wrong. This guide covers the most frequent causes of CSV import failures in NetSuite and gives you clear, tested fixes for each one.

Most CSV import errors fall into a handful of predictable categories. Once you know what to look for, you can fix problems in minutes instead of hours. This guide works through each category with specific solutions you can apply immediately.

6 Common CSV Import Failures and Their Fixes

Character Encoding Issues

This is the single most common cause of mysterious import failures. If your CSV file contains special characters — accented names, currency symbols, or data copied from Word or PDF documents — and the file is not saved as UTF-8, NetSuite will either reject the file or import garbled data. The fix is simple but easy to overlook: always save your CSV as UTF-8. In Excel, use 'Save As' and select 'CSV UTF-8'. In Google Sheets, the default export is already UTF-8. If you are generating files programmatically, make sure your script explicitly writes UTF-8 with a BOM (byte order mark) for maximum compatibility.

Column Header Mismatches

NetSuite's CSV Import Assistant maps your column headers to internal field names, and it is surprisingly strict about exact matches. A column called 'Customer Name' will not automatically map to NetSuite's 'Company Name' field. Extra spaces, different capitalisation, or slightly different wording will all cause fields to be skipped or the import to fail entirely. The safest approach is to download a sample export of the record type you are importing, then use those exact column headers in your import file. For custom fields, use the internal ID (prefixed with 'custbody_' or 'custcol_') rather than the display label, as labels can be changed by administrators without warning.

Date and Number Format Conflicts

Date formats are a persistent source of import errors, especially in organisations that operate across the UK and US. NetSuite expects dates in the format set in your company preferences — typically DD/MM/YYYY for UK accounts or MM/DD/YYYY for US accounts. If your CSV contains dates in the wrong format, NetSuite will either reject them or, worse, silently swap the day and month, turning 3rd February into 2nd March. Number formats cause similar problems: NetSuite may expect a period as the decimal separator, but your source data uses commas. Before importing, check your NetSuite company preferences under Setup > Company > General Preferences and ensure your CSV matches exactly.

Missing or Invalid Record References

Many NetSuite fields are references to other records — a sales order references a customer, an invoice references an item. When importing, you need to provide either the internal ID or the exact name/number that NetSuite can look up. If the referenced record does not exist, or if the name does not match exactly, the import row will fail. This is particularly common when importing transactions that reference customers, items, or employees. The most reliable approach is to use internal IDs for all reference fields. You can find these by running a saved search on the referenced record type and including the internal ID column. For subsidiary, department, class, and location fields, make sure the referenced values exist and are active — inactive records will be rejected.

Duplicate Detection and Overwrite Errors

NetSuite has built-in duplicate detection, and if your import file contains records that match existing data, the import will either fail or create unwanted duplicates depending on your settings. When updating existing records, you must include a unique identifier — typically the internal ID or external ID — and set the import to 'Update' mode rather than 'Add'. If you are adding new records and getting duplicate errors, check whether NetSuite's duplicate detection rules are matching on fields like email address or company name. You can review these rules under Setup > Company > Auto-Generated Numbers or the relevant record type's duplicate detection settings. For large imports, it is worth doing a dry run with a small subset of rows first to catch these issues early.

File Structure and Formatting Problems

Sometimes the CSV file itself is the problem, not the data inside it. Common structural issues include: empty rows at the end of the file (Excel often adds these invisibly), multiple header rows, merged cells from a copied spreadsheet, or line breaks within a cell value that split a single record across multiple rows. Another frequent issue is using the wrong delimiter — NetSuite expects comma-separated values, but some European systems export with semicolons. Before uploading, open your CSV in a plain text editor (not Excel) and check that each row contains the same number of commas, there are no blank rows, and multi-line cell values are properly enclosed in double quotes. Cleaning up these structural issues before import will save you significant troubleshooting time.

Bringing It All Together

CSV imports do not have to be painful. The vast majority of failures come down to encoding, formatting, and reference mismatches, all of which are straightforward to fix once you know what to look for. Build good habits around file preparation, use internal IDs wherever possible, and always test with a small batch first. If import reliability is still inconsistent, a focused NetSuite data import review can help you standardise templates and reduce repeat failure points before they affect month-end reporting.