Diagnose a failed import, step by step

What you will achieve. You will learn to answer "where did my import stop, and why?" in a minute, by working through three files that fail in three different places: one with bad rows, one with the wrong columns, one that passes the review and fails only when it is published.

You need. A connected WordPress site, and the files 09-articles-with-problems.csv, 10-semicolon-separated.csv and 12-empty-status-and-date.csv. Difficulty: intermediate. Time: about 25 minutes.

Step 0: where can an import stop?#

A file goes through stages, and each shows its trouble in its own place:

The status on the Uploads list tells you which stage a file is in (statuses).

Part 1: rows with errors#

1. Create a configuration from 09-articles-with-problems.csv for WordPress Posts: the editor chooses Title, Status and Publish date from the column names; set the category column to Category (create a configuration).
2. Drop 09-articles-with-problems.csv on its card.
3. The review says 3 new and 4 errors. Select Errors:

The line under the Publish button says 4 rows with errors will be skipped. Fix the cells in your copy of the file and upload it again: the rows that were fine show as unchanged, the corrected ones as new (row errors).

Part 2: a file that does not match#

Now drop 10-semicolon-separated.csv on the same configuration. It has an ID, a Title, a Category and Tags, but not the columns the configuration also uses.

Nothing was processed. The box lists each missing column with the field that uses it, and the new column Tags that the configuration does not use. There is nothing to fix in the rows: either the file is wrong (add the columns), or the configuration is (columns are missing). Update mapping for this file points the fields at other columns and checks the file again.

Part 3: an item that fails only when it is published#

Create a second configuration the same way from 12-empty-status-and-date.csv (Title, Body, Category, Publish date and Status columns), and drop the file.

1. The review says 4 new and 0 errors. Two cells are empty: HLJ-802 has no Status, and HLJ-803 has no Publish date. Neither is a problem.

2. Publish. All four articles are created. The site decides what the two empty cells could not say: the article without a Status is a draft, and the article without a Publish date is published at the moment you pressed Publish (empty cells).

Now make a problem that only the site can report.

3. In your copy of the file, change the text in the Body of two rows (HLJ-801 and HLJ-804) and drop it on the configuration again. The review says 2 updated and 2 unchanged: the two rows with empty cells are not changes.
4. Before you press Publish, open WordPress and move the article An article that publishes fine to the trash (Posts → Move to Trash). A colleague could just as well have done it while the file waited for review.
5. Publish. The page ends with Published with errors: one published, one failed.

6. Select See why they failed and retry them safely. On Sites, the result is red and says The mapped WordPress item is in the trash. Restore it as a draft or delete it permanently, then retry safely.

7. Read the message and decide. The cause is on your site, not in your file, so Retry safely helps once the cause is gone. In WordPress, open Posts → Trash and restore the article, then select Retry safely on the result. It becomes queued, then sending, then succeeded, and the article holds the revised text. Nothing was published twice (retry failed items safely).

What to take away#

• Ask first where it stopped, then read the message in that place.
• A skipped row is not a failure. Fix the cell and upload again; good rows are never published twice.
• The review cannot see everything. The site can change between the review and Publish, and only the site can report it. The Sites page keeps the reason, and Retry safely sends the same content again once it is fixed.
• Every message is in the error list, each linked to its guide.