A failed CSV import should not send a SaaS customer back to the beginning
Startups and B2B SaaS
Published Updated 4 min read
The file uploads. A progress bar completes. Then the product reports that some records failed, and the customer has to decide whether uploading the file again will fix the problem or duplicate the records that already succeeded.
For a B2B SaaS team, that uncertainty is an onboarding problem worth designing in its own right. A useful import flow shows what the product accepted, what it rejected, and how the customer can correct the remaining work safely.
The scenario is illustrative. The design principle applies whenever a customer brings existing work into a new system and needs to trust the result.
What should the product explain before the upload?
Show the required fields and any constraints that affect the customer’s preparation. Provide a representative example rather than an empty template with unexplained column names.
Explain how the product identifies an existing record. A customer needs to know whether an import creates new records, updates existing ones, or asks them to choose. The interface should describe the actual behavior that engineering supports.
Separate file problems from record problems. An unsupported file type prevents reading the file. A missing value may affect only one row. An unfamiliar owner may require a mapping decision. These failures should not all produce the same message.
If an import is a long-running job, let the person understand whether it continues when they leave the page. Do not imply that closing the tab cancels the work unless that is how the system behaves.
What should the preview reveal?
Before committing changes, show enough of the mapping and proposed result for the customer to catch a consequential mistake. The preview might identify the destination field, a sample value, and whether the product will transform it.
In an illustrative customer database, a column called “Owner” could contain email addresses while the destination expects internal user IDs. A preview that displays only the column names can miss the mismatch. A useful preview makes the unresolved ownership decision visible.
Use a proposed state checklist:
| State | Information the customer needs |
|---|---|
| File cannot be read | The specific file problem and a supported next step |
| Mapping needs attention | The affected fields and the decisions required |
| Import is running | Progress that reflects the job’s actual state |
| Some records succeeded | Separate accepted and rejected results |
| Correction is ready | Which records will be retried and how duplicates are handled |
| Import completed | A way to inspect the result in the product |
The checklist describes customer needs. Engineering must define the behavior behind each state, including the limits of cancellation and retry.
What makes an error message actionable?
Connect the message to the affected record and the correction the person can make. Preserve useful work where possible. If the product can provide a file containing only rejected rows, explain how the customer should use it and what happens when those rows return.
Avoid displaying sensitive information more widely than the user’s permissions allow. An error report is still part of the product’s access model.
The turning point in a test is often the second attempt. A participant may understand the first error but remain afraid to retry because the product has not explained what already happened. Ask them to describe the expected result before they submit the correction.
The GOV.UK usability-testing guidance provides a useful method: observe people attempting a believable task with neutral instructions. For an import, include a recoverable error in the supplied test file and watch the recovery as well as the upload.
What should an agency’s scope include?
Ask a SaaS design partner to cover the full job: preparation, mapping, progress, partial success, correction, and inspection of the result. Confirm who will work with engineering on data rules and retry behavior.
Request a testable prototype with realistic sample data. Beautiful empty screens do not show whether long identifiers, inconsistent values, or large error lists remain usable.
Humbleteam’s B2B SaaS design guide covers broader partner selection. This narrower brief helps distinguish an agency that can improve a live operational workflow from one offering a visual refresh alone.
What counts as a better import?
Measure whether eligible customers reach a usable result, how much assistance they need, and whether corrected attempts introduce new problems. Separate file-level success from successful records. Keep the underlying counts and compare equivalent import types.
End the flow where the customer can inspect and use the imported work. A completed progress bar tells them that a process stopped. The product should also help them verify what they now have.
