Our first app, Migrato, is live on the Shopify App Store - free plan, no credit card. Take a look
Home / Documentation / Troubleshooting Guide
Troubleshoot

Troubleshooting Guide

Causes and fixes for common import, export, FTP/SFTP, scheduling and file issues.
14 min read Updated 13 October 2026 Applies to Migrato on all plans

The Troubleshooting Guide helps you identify and resolve common issues that may occur while using Migrato for Shopify data import, export, migration, FTP/SFTP file transfers, scheduled jobs, and file processing.

If a job does not complete as expected, first check the job status, error message, input file, selected entity, and configured options. The following troubleshooting scenarios cover common issues and recommended solutions.

1. FTP/SFTP connection failed

Migrato is unable to connect to the configured FTP/SFTP server.

This can happen when the server details, credentials, connection type, port, or server permissions are incorrect.

Possible causes:

  • Incorrect server/host name.
  • Incorrect username or password.
  • Incorrect port.
  • Incorrect server type selected.
  • FTP/FTPS or SFTP configuration does not match the server.
  • The server blocks Migrato's connection.
  • The required folder/path does not exist.
  • The user does not have permission to access the folder.
  • Firewall or IP restrictions are blocking the connection.

How to troubleshoot:

  1. Open Migrato → Settings → Servers.
  2. Select the configured server.
  3. Verify the Server Type.
  4. Check the server/host name.
  5. Verify the username and password.
  6. Verify the port configured on the server.
  7. Check the configured folder/path.
  8. Confirm that the FTP/SFTP user has the required permissions.
  9. Check whether your server firewall or security settings restrict external connections.
  10. Save the server configuration and try the operation again.

Migrato supports server configurations such as:

Server type Description
FTP/FTPS FTP connection, including FTP with TLS.
SFTP Secure File Transfer Protocol connection.
!
FTP/FTPS and SFTP are different

FTP/FTPS and SFTP are different connection methods. Select the server type that matches your hosting/server configuration.

2. Invalid details error when importing

An import job may show an Invalid Details or similar validation error when Migrato cannot process one or more values from the uploaded file.

Possible causes:

  • Incorrect column names.
  • Missing required data.
  • Invalid values.
  • Incorrect date or number format.
  • Invalid Shopify identifiers.
  • Incorrect relationship/mapping between records.
  • Unsupported values in a field.
  • Data is placed in the wrong column.
  • The file was manually modified and the expected template structure was changed.

How to troubleshoot:

  1. Check the import job's error/result file.
  2. Identify the row containing the invalid data.
  3. Check the corresponding column.
  4. Compare the column structure with the relevant Template Documentation.
  5. Correct the invalid value.
  6. Save the file as CSV or XLSX.
  7. Upload the corrected file again.
  8. Run the import again.
★
Start from a Migrato file

Using a Migrato demo/export file as a starting template can help prevent column-name and data-structure issues.

3. Import file cannot be processed

Migrato cannot read or process the uploaded import file.

Possible causes:

  • Unsupported or corrupted file.
  • Incorrect file format.
  • Empty file.
  • Missing headers.
  • Incorrect worksheet selected or structured.
  • Invalid CSV formatting.
  • Unexpected characters or encoding issues.
  • File does not contain the expected entity data.

How to troubleshoot:

  1. Confirm that the file is a supported CSV or XLSX file.
  2. Open the file and verify that it contains data.
  3. Check that the first row contains the expected column headers.
  4. Compare the file with the relevant template documentation.
  5. Remove unnecessary blank rows or columns.
  6. Check for incorrectly formatted values.
  7. Save the file again and retry the import.

4. Required data is missing

The import job fails because required information is missing from one or more records.

For example, a record may be missing information required to identify or create the Shopify object.

How to troubleshoot:

  1. Open the import file.
  2. Identify records with blank required fields.
  3. Check the entity's Template Documentation.
  4. Add the required values.
  5. Save the file.
  6. Re-upload the corrected file.
★
Not every column is required

Not every available column is required for every import. Only provide the fields required for your intended operation and the fields you want to create or update.

5. Incorrect column or header name

Migrato cannot correctly map data because the column header in the import file does not match the expected template.

Possible causes:

  • Header renamed manually.
  • Spelling changed.
  • Extra spaces added.
  • Column renamed to a Shopify Admin label instead of the Migrato field name.
  • Columns from another entity were included.

How to troubleshoot:

  1. Compare the file headers with the relevant Template Documentation.
  2. Check the exact column names.
  3. Restore changed headers.
  4. Remove unsupported columns if necessary.
  5. Save and retry the import.

Example: if the template expects the first header below, avoid changing it to the second, unless that is the documented field name for the selected entity.

Column header
# Expected
Handle

# Avoid
Product Handle

6. Duplicate records during import

Records are duplicated or an import does not update the expected existing records.

Possible causes:

  • The file does not contain the identifier required to match an existing record.
  • The identifier is incorrect.
  • The import operation is configured differently from the intended update/create workflow.
  • Duplicate records already exist in the source file.

How to troubleshoot:

  1. Check the entity's identifying fields.
  2. Verify the IDs, handles, codes, or other supported identifiers.
  3. Check whether the same record appears multiple times in the file.
  4. Review the selected import operation.
  5. Remove unintended duplicate rows.
  6. Retry the import.

7. Import creates new records instead of updating existing records

Existing Shopify records are not updated and new records are created instead.

Possible causes:

  • Existing record identifier is missing.
  • Identifier does not match the Shopify record.
  • Handle or other matching value has been changed.
  • The import file was prepared from a different store.

How to troubleshoot:

  1. Export the existing Shopify data from Migrato.
  2. Use the exported file as the starting point for your update.
  3. Keep the relevant identifying fields unchanged.
  4. Modify only the fields that need to be updated.
  5. Import the file again.
★
Recommended approach

For bulk updates, exporting existing data first and modifying that file can help preserve the correct record identifiers and structure.

8. Invalid Shopify ID

An import fails because an ID provided in the file cannot be matched or processed.

Possible causes:

  • ID belongs to another Shopify store.
  • ID was modified.
  • ID is incomplete.
  • Incorrect ID type was provided.
  • The referenced Shopify record does not exist.

How to troubleshoot:

  1. Verify the ID in the source file.
  2. Confirm that the ID belongs to the current Shopify store.
  3. Export the relevant entity from the current store.
  4. Compare the IDs.
  5. Replace incorrect IDs where appropriate.
  6. Retry the import.

9. Invalid URL or file URL

Migrato cannot access a file provided through a URL.

Possible causes:

  • URL is not publicly accessible.
  • URL requires authentication.
  • URL has expired.
  • File was removed.
  • Server blocks external requests.
  • URL points to a web page rather than the actual file.

How to troubleshoot:

  1. Open the file URL in a browser.
  2. Confirm that the URL directly provides the file.
  3. Check whether authentication is required.
  4. Confirm that the file still exists.
  5. Verify that the URL has not expired.
  6. Use a publicly accessible file URL and retry the import.

10. FTP/SFTP file not found

The connection to the FTP/SFTP server succeeds, but Migrato cannot find the specified file.

Possible causes:

  • Incorrect folder/path.
  • Incorrect file name.
  • File was moved or deleted.
  • File name is case-sensitive.
  • The configured FTP/SFTP user cannot access the folder.

How to troubleshoot:

  1. Verify the file exists on the server.
  2. Check the exact file name.
  3. Check uppercase/lowercase characters.
  4. Verify the directory/path.
  5. Confirm that the FTP/SFTP account has read permission.
  6. Retry the import.

11. FTP/SFTP file upload failed

Migrato completes the export, but cannot upload the results file to the configured FTP/SFTP server.

Possible causes:

  • Incorrect server details.
  • Missing write permission.
  • Destination folder does not exist.
  • Server storage is full.
  • Firewall restrictions.
  • Connection was interrupted.

How to troubleshoot:

  1. Verify the server connection.
  2. Check the destination folder.
  3. Confirm that the account has write permission.
  4. Check available server storage.
  5. Verify the configured server type and credentials.
  6. Run the export again.

12. Invalid date or time format

An import fails because a date or time value cannot be processed.

Possible causes:

  • Incorrect date format.
  • Invalid date.
  • Unexpected time-zone information.
  • Date entered as free-form text.
  • Date format differs from the expected template.

How to troubleshoot:

  1. Check the relevant template documentation.
  2. Compare the date format with an exported sample.
  3. Correct invalid dates.
  4. Avoid unnecessary manual formatting changes.
  5. Retry the import.

13. Invalid numeric value

A field containing a number, amount, quantity, or other numeric value cannot be processed.

Possible causes:

  • Text entered instead of a number.
  • Currency symbols included where they are not expected.
  • Incorrect decimal separator.
  • Invalid characters.
  • Extra spaces.

How to troubleshoot:

  1. Identify the affected column.
  2. Check an exported sample.
  3. Remove unsupported characters.
  4. Use the expected numeric format.
  5. Save and retry the import.

14. Job failed

An import or export job shows a Failed status.

How to troubleshoot:

  1. Open Migrato → All Jobs.
  2. Locate the failed job.
  3. Check the entity and operation.
  4. Review the input file and selected options.
  5. Check the job result/error information.
  6. Identify the failed records or data.
  7. Correct the source data or configuration.
  8. Run the job again.
★
Check the error before retrying

Do not repeatedly retry the same failed file without checking the error details. Correcting the underlying data or configuration first can prevent repeated failures.

15. Job is still processing

A job remains in a processing state for longer than expected.

Possible causes:

  • Large amount of data.
  • Complex import/export operation.
  • Large files.
  • Shopify API processing.
  • Multiple jobs running at the same time.
  • Scheduled jobs waiting for processing.

How to troubleshoot:

  1. Open All Jobs.
  2. Check the job status.
  3. Review the number of records being processed.
  4. Check whether other jobs are running.
  5. Allow the job time to complete.
  6. If the job remains stuck, review its details and contact support if required.

16. Scheduled job did not run

A scheduled import or export did not start at the expected time.

Possible causes:

  • Schedule was not configured correctly.
  • Scheduled date/time has not been reached.
  • Job was cancelled.
  • Schedule configuration was changed.
  • The job is waiting in the queue.
  • Account or plan limitations may affect the operation.

How to troubleshoot:

  1. Open the scheduled job.
  2. Check the configured Schedule On date.
  3. Check the configured time.
  4. Verify the repeat interval, if applicable.
  5. Check the job in All Jobs.
  6. Review the current job state.
  7. Confirm that the scheduled job was not cancelled.

17. Export contains no data

An export completes but contains no records or fewer records than expected.

Possible causes:

  • Filters are too restrictive.
  • The selected entity does not contain matching records.
  • Incorrect filter values.
  • Date filter excludes the required records.
  • Selected columns do not include the expected information.

How to troubleshoot:

  1. Review the selected entity.
  2. Review all applied filters.
  3. Remove unnecessary filters.
  4. Run a test export without filters.
  5. Compare the results.
  6. Add filters back one at a time.

Example: if an export uses:

  • Status = Published
  • Updated At = a specific date range

records outside that date range or with another status will not be included.

18. Filter does not return expected records

The export results do not match the expected records.

How to troubleshoot:

  1. Review the selected filter.
  2. Check the filter value.
  3. Check whether multiple filters are applied.
  4. Review the date range.
  5. Remove filters and test again.
  6. Add filters one at a time to identify which filter excludes the records.
★
Review active filters

When using multiple filters, the results are limited according to the conditions selected. Always review the active filter chips before starting the export.

19. Export file is missing expected columns

The exported file does not contain a field you expected.

Possible causes:

  • The column was not selected.
  • The field belongs to another column group.
  • The field is export-only.
  • The selected entity does not support that field.

How to troubleshoot:

  1. Open the entity export configuration.
  2. Select Select Columns.
  3. Review all available column groups.
  4. Select the required column.
  5. Run the export again.
i
Export-only fields

Some fields may be available only for export and may not be supported during import.

20. Metafield data is missing

Expected metafield information is not present in the import/export file.

How to troubleshoot:

  1. Open Select Columns for the relevant entity.
  2. Check whether a Metafield column is available.
  3. Select the required metafield field.
  4. Verify the metafield data in the file.
  5. Check that the metafield definition exists and is supported by the Shopify store.
  6. Retry the operation.

21. Product or collection relationships are incorrect

Related records such as products, collections, customers, locations, or other linked data are not associated as expected.

Possible causes:

  • Incorrect ID.
  • Incorrect handle.
  • Missing relationship data.
  • Source and destination stores contain different IDs.
  • Related record was not imported first.

How to troubleshoot:

  1. Verify the source and destination identifiers.
  2. Check handles and IDs.
  3. Confirm that referenced records exist.
  4. Import dependent records before records that reference them when required.
  5. Review the result file for failed relationships.
  6. Retry the affected data.

22. Import is rejected because of plan limits

The number of records in a job exceeds the limit available on the current Migrato plan.

How to troubleshoot:

  1. Open Plans.
  2. Check the Limit Per Job for the selected entity.
  3. Compare it with the number of records in your file.
  4. Split the data into smaller files if appropriate.
  5. Alternatively, upgrade to a plan with a higher limit.

Example: if the current plan supports 6,000 Products per job and your file contains 10,000 products, you can either:

  • Split the file into multiple jobs, if suitable for your workflow, or
  • Upgrade to a plan with a higher product limit.

23. Import result contains errors

The import completes but some records contain errors.

How to troubleshoot:

  1. Open the completed import job under All Jobs.
  2. Download or open the available result file.
  3. Identify the records that were not imported successfully.
  4. Review the error information.
  5. Correct the affected records.
  6. Create a corrected file.
  7. Import the corrected records again.
★
Recommended approach

Do not modify successfully imported records unless they also require changes. Focus the corrective import on failed or incomplete records.

24. Notification email was not received

A Migrato job notification email was not received.

How to troubleshoot:

  1. Open Settings → Notifications.
  2. Check the configured email addresses.
  3. Verify that the required event is enabled.
  4. Check whether the notification is configured for Manual, Scheduled, or both.
  5. Check the email account's spam/junk folder.
  6. Verify that the email address is correct.
  7. Save the notification settings if changes were made.

Notifications can be configured for events such as:

Event Manual Scheduled
Job Started Selectable Selectable
Job Queued Selectable Selectable
Job Cancelled Selectable Selectable
Job Failed Selectable Selectable
Job Finished Selectable Selectable

25. Job file is no longer available

A previously generated import/export file cannot be accessed.

Possible cause: Migrato provides Job Files Erasure settings that control how long job files are retained.

How to troubleshoot:

  1. Open Settings → Job Files Erasure.
  2. Review the current file-retention setting.
  3. Check whether older job files have been automatically removed.
  4. If the file was already deleted, generate a new export or re-upload the required import file.
✕
Deleted job files are not recoverable

If files are deleted, they may also be unavailable to support when investigating an issue.

26. Cannot access deleted job files

A previously deleted job file is required for troubleshooting or support.

Solution: Deleted files cannot be recovered through Migrato. If a file is required for future troubleshooting, keep a local copy before it is removed by the configured file-erasure policy.

27. How to check a job before contacting support

Before contacting support, collect the following information:

Information Why it helps
Job ID Helps identify the specific job.
Entity Identifies the Shopify data type being processed.
Import/Export Identifies the operation being performed.
Job Status Shows whether the job is processing, finished, cancelled, or failed.
Input File Helps identify source-data problems.
Result/Error File Provides information about failed records.
Error Message Helps identify the underlying issue.
Filters Helps determine whether records were excluded.
Selected Columns Helps verify the exported/imported structure.
FTP/SFTP Details Required when the issue involves a remote server.

When an import or export does not work as expected, follow this general process:

  1. Check the job. Go to Migrato → All Jobs and locate the affected job.
  2. Check the status. Review whether the job is Processing, Finished, Cancelled, Failed or Queued.
  3. Check the entity. Confirm that you selected the correct Shopify entity, such as Products, Customers, Orders, Collections, Discounts, Pages, Files, Metaobjects, Menus or another supported entity.
  4. Check the file. For imports, verify the file format, column headers, required data, IDs/handles, dates, numeric values, relationships and duplicate records.
  5. Check filters. For exports, review the applied filters and remove unnecessary filters to determine whether they are excluding records.
  6. Check settings. For FTP/SFTP, scheduling, notifications, or file retention issues, review the relevant settings.
  7. Retry. After correcting the issue, run the import/export again.
  8. Review the result. Check the completed job and result/error information to confirm that the issue has been resolved.

Troubleshooting quick reference

Problem First thing to check
FTP/SFTP connection failed Server type, host, port, username, password
Invalid Details error Import file values and template structure
File cannot be processed CSV/XLSX format and headers
Required data missing Required fields in the template
Duplicate records IDs/handles and duplicate rows
Existing records not updated Matching identifier
Invalid Shopify ID ID belongs to the current store
File URL failed URL accessibility and file availability
FTP/SFTP file not found File path, file name, and permissions
FTP/SFTP upload failed Destination path and write permissions
Export has no data Selected filters
Missing export columns Select Columns configuration
Metafields missing Metafield column selection
Job failed Job details and result/error file
Job stuck processing Job status and processing volume
Scheduled job did not run Schedule date, time, and job status
Import exceeds limit Current plan's Limit Per Job
Notification not received Notification settings and email address
Old file unavailable Job Files Erasure settings
Deleted file required Deleted files cannot be recovered
★
Start with All Jobs

For the fastest troubleshooting, start with All Jobs, identify the affected job, review its status and result/error information, and then check the source file or configuration related to that job.

Ready to run this on your own store?

Migrato's free plan handles 25 items per job - enough to follow any page in these docs end to end before you pay anything.

Free plan forever No credit card 2-minute setup Uninstall anytime