Pyle

How to Troubleshoot a Failed Import ​

What This Task Does ​

This task helps you diagnose why a spreadsheet import failed in Tools > Excel and decide what to fix before you try the import again.

Use it when an import is marked failed, or when an import appears to be stuck because it has not finished validating cleanly.

Before You Start ​

Make sure:

  • you have access to Tools > Excel
  • you know which import template you used
  • you have the source workbook or can recreate it
  • you understand whether the import expects one sheet or multiple sheets

The failure details live in the import logs, not in the spreadsheet itself.

Steps ​

  1. Open Tools > Excel.
  2. Stay on the Import tab.
  3. Find the failed import run in the table.
  4. Open the row action that shows the import logs.
  5. Read the row-level errors carefully and note the first missing field, bad value, or sheet mismatch.
  6. Check whether the workbook matches the template expectations for:
    • sheet names
    • required columns
    • column order if the template depends on it
    • required identifiers or lookup values
  7. Fix the source workbook.
  8. Run the import again with the corrected file.
  9. Review the new run status and logs before assuming the problem is resolved.

What Happens Next ​

After you resubmit the import, the run is processed asynchronously again.

If the fix was correct, the run should move from pending or processing to completed. If it fails again, the new logs usually point to the next bad row or field that still needs attention.

Common Mistakes ​

  • retrying the same workbook without fixing the logged error
  • checking the table status but not opening the row logs
  • forgetting that some templates expect multiple sheets
  • using the wrong template for the type of data in the workbook
  • assuming a queued import failed before it has finished processing

Sources ​

  • packages/admin/src/Livewire/Admin/Tools/Excel/Page.php
  • packages/admin/src/Livewire/Admin/Tools/Excel/DataTable.php
  • packages/admin/src/Livewire/Admin/Tools/Excel/ImportDialog.php
  • packages/admin/src/Livewire/Admin/Tools/Excel/LogsDialog.php
  • packages/framework/src/Models/ExcelImport.php
  • packages/framework/src/Models/ExcelImportLog.php
  • packages/framework/src/Actions/Excel/ExcelImporter.php
  • packages/framework/src/Actions/Excel/SetImportStatus.php