Troubleshoot and roll back imports
This guide covers the three things that go wrong after you start an Import: fixing per-row validation errors, recovering an import stuck in a transient state, and rolling back an import you have already committed. Use it once your import is created and you are working on its detail page.
- Role required: the same contributor access that created the import. Fixing rows and re-validating need pre-commit access to the import's Site or Project; Rollback, Reset to Draft, and Dismiss need post-commit access to that scope.
- Prerequisites: an existing import. See Import data to create one and How the import pipeline works for the status lifecycle.
Fix per-row validation errors
When you select Validate, Erde checks every row and sets each to Valid or Invalid. If any row is Invalid, the import moves to Validation Failed and you fix the rows before committing.
- Go to Imports and open the import. Each entity tab is captioned with its row count; a tab with invalid rows shows an error marker. The grid loads one page at a time — use the First / Previous / Next / Last controls, the Go to page box, and the Rows per-page selector to move through large imports.
- Select the Errors only filter to hide passing rows and show only the ones that need attention. The filter runs on the server, so it finds invalid rows across the whole import, not just the current page.
- Read the Feedback column on each invalid row. It names the field and the problem (for example, a value that is not a valid number, or a referenced Location that does not exist).
- To narrow further, select Filters and add column conditions (column + Equals / Does not equal / Contains / Is blank + value); all conditions must match. The filter runs on the server and combines with Errors only.
- Edit the offending cell in place. If View original is on, turn it off first — you cannot edit rows while it is on. Each edit saves immediately; the row returns to Pending and the import drops back to Draft, because a prior validation pass no longer applies.
- When the same bad value appears on many rows, use Replace All to fix them at once: pick the column, the value to find, and the replacement, optionally Preview matches first. It applies across the rows the current filter is showing and returns each to Pending.
- Select Validate again. Repeat until no rows are Invalid.
When validation finds no invalid rows but every row would be skipped or excluded, the import lands in Nothing to Commit rather than failing. Erde shows the reason in a banner — typically "All rows matched existing data and would be skipped. There is nothing to commit." or "All rows are excluded. Restore at least one row before committing." Modify the data, restore excluded rows, or upload a different file, then re-validate.
A committed import is read-only: its rows become editable again only after you roll it back and reset it to Draft (see Roll back a committed import).
Export errors, warnings, and information
When an import has thousands of rows, paging the grid to find every problem is slow — and you often want to hand the whole list to whoever produced the file. For a Lab Report, that means giving the lab the exact list of what to correct in their EDD and resend. Three buttons in the import's header give you a downloadable summary:
- Export Errors appears whenever the import has invalid rows. This is the must-fix list — the validation errors that have to be corrected before the import can commit.
- Export Warnings appears whenever the import has warning rows. Warnings are non-blocking concerns on otherwise-valid rows — for example, an analysis whose matrix does not match its sample's matrix. They are for your own review, so they download separately and never clutter the errors list you share with a lab.
- Export Information appears whenever the import has informational notes. These record something the import did on your behalf — an analyte resolved from an alias to its canonical name, or a default applied to a blank cell — so you can review the automatic choices afterward.
Each file is a rolled-up summary, not a row-by-row dump: identical problems collapse to a single line, so one misspelled analyte repeated across 18,000 rows is one line, not 18,000. Each line lists:
| Column | What it tells you |
|---|---|
| Sheet / Section | Which sheet the rows came from — Result, Analysis, Sample, or Lab Report for a multi-sheet lab EDD; the single source sheet otherwise |
| Field | The column the problem is about |
| Problem (errors) / Note (warnings) | The validation message, verbatim |
| Affected Rows | How many rows have this exact problem |
| Example Rows | A few of the affected row numbers, to help locate them |
Lines are ordered most-affected first, so the biggest problems sit at the top. Sheet / Section plus the row number pinpoint each problem in the file you uploaded — the row numbers match the lines in your original sheet. The summary downloads as Excel (.xlsx).
Recover a stuck import
Validating, Committing, and Rolling Back are transient states. If the server restarts or crashes mid-operation, an import can be left pinned in one of them. Erde recovers these automatically — you do not intervene.
A background recovery sweep runs when the server starts and then re-runs every 5 minutes. It looks for imports that have sat in a transient state longer than a 5-minute grace window and moves each to a failed state you can act on:
| Stuck status | Recovered to | Message shown |
|---|---|---|
| Validating | Validation Failed | "Server restarted during validation. Please re-validate." |
| Committing | Commit Failed | "Server restarted during commit. Please re-validate and retry." |
| Rolling Back | Rollback Failed | "Server restarted during rollback. Manual intervention may be required." |
The grace window prevents a healthy in-progress operation from being marked stuck. A genuinely long commit — for example, millions of Logger Readings — is excluded from the sweep while it runs, so it is never mistaken for stuck.
After recovery, open the import and act on its new status:
- Commit Failed — for most formats the commit is atomic, so nothing was created. Re-validate, then commit again. (Logger telemetry commits in batches; re-committing purges this import's partial records first, so it stays consistent.)
- Validation Failed — re-validate.
- Rollback Failed — retry Rollback, or select Dismiss if you no longer want to roll back (see below).
Roll back a committed import
Rolling back removes the records the import created. Every record Erde creates during a commit is stamped with that import's id; rollback deletes exactly those rows. Records the import only reused or appended to are not stamped and are never touched.
Rollback permanently deletes every record this import created. There is no per-record undo. Confirm the import is the one you mean to reverse before you proceed.
- Go to Imports and open the committed import. Its status is Committed.
- Select Rollback. The Rollback Import dialog confirms "This will delete all N entities created by this import."
- Confirm. The import moves to Rolling Back, deletes its stamped records in one transaction, and finishes at Rolled Back. Rollback is fast and synchronous — the page updates as soon as it completes.
Figure: the post-commit lifecycle. A failed rollback deletes nothing, so dismissing it safely returns the import to Committed.
Reset or delete after rollback
A Rolled Back import is deletable and resettable:
- Select Reset to Draft to clear the commit and rollback metadata and re-open the rows for editing. You can then validate and commit again.
- Select the trash button (Delete Import) to remove the import record entirely.
Revert to original
If you have edited rows before committing and want to start over from the file Erde first parsed, revert to original restores the originally parsed data and discards your saved edits. This is different from rollback, which undoes a committed import.
- Whole import: select Revert to Original in the toolbar. Every row returns to its originally parsed values.
- Single row: right-click the row, select Revert Row to Original, and confirm. Only that row is restored.
Reverting returns the import to Draft, so re-validate afterward. It is available before commit — a committed import must be rolled back and reset to Draft first.
Result
A fixed import re-validates to Ready to Commit (or Nothing to Commit when there is genuinely nothing to do). A recovered import sits in a failed status with a message telling you what to do next. A rolled-back import shows Rolled Back and can be reset or deleted.
Troubleshooting
| Symptom | Cause | Resolution |
|---|---|---|
| Status is Validation Failed after validating | One or more rows are Invalid | Filter to Errors only, fix each row's Feedback, save, and re-validate — or Export Errors for the full list to hand to your lab |
| Status is Nothing to Commit | Validation passed but all rows would be skipped or are excluded | Modify the data, restore excluded rows, or upload a different file, then re-validate |
| Commit button is missing | The import is not in Ready to Commit | Re-validate; commit is available only from Ready to Commit |
| Status is Commit Failed | The server restarted mid-commit, or the commit threw | Re-validate and commit again; atomic formats created nothing, so no cleanup is needed |
| Rollback returns "some imported entities are now referenced by other data and cannot be deleted" | Another record now references data this import created | Remove the dependent data first, then retry Rollback |
| Status is Rollback Failed | The rollback could not complete | A failed rollback deletes nothing — retry Rollback, or select Dismiss to return the import to Committed |
| Delete returns "created data that is still referenced and could not be removed" | The committed import's records are still in use | Roll back the import (or remove the dependent data) first, then delete it |