Troubleshooting Guide
Causes and fixes for common import, export, FTP/SFTP, scheduling and file issues.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:
- Open Migrato → Settings → Servers.
- Select the configured server.
- Verify the Server Type.
- Check the server/host name.
- Verify the username and password.
- Verify the port configured on the server.
- Check the configured folder/path.
- Confirm that the FTP/SFTP user has the required permissions.
- Check whether your server firewall or security settings restrict external connections.
- 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 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:
- Check the import job's error/result file.
- Identify the row containing the invalid data.
- Check the corresponding column.
- Compare the column structure with the relevant Template Documentation.
- Correct the invalid value.
- Save the file as CSV or XLSX.
- Upload the corrected file again.
- Run the import again.
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:
- Confirm that the file is a supported CSV or XLSX file.
- Open the file and verify that it contains data.
- Check that the first row contains the expected column headers.
- Compare the file with the relevant template documentation.
- Remove unnecessary blank rows or columns.
- Check for incorrectly formatted values.
- 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:
- Open the import file.
- Identify records with blank required fields.
- Check the entity's Template Documentation.
- Add the required values.
- Save the file.
- Re-upload the corrected file.
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:
- Compare the file headers with the relevant Template Documentation.
- Check the exact column names.
- Restore changed headers.
- Remove unsupported columns if necessary.
- 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.
# 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:
- Check the entity's identifying fields.
- Verify the IDs, handles, codes, or other supported identifiers.
- Check whether the same record appears multiple times in the file.
- Review the selected import operation.
- Remove unintended duplicate rows.
- 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:
- Export the existing Shopify data from Migrato.
- Use the exported file as the starting point for your update.
- Keep the relevant identifying fields unchanged.
- Modify only the fields that need to be updated.
- Import the file again.
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:
- Verify the ID in the source file.
- Confirm that the ID belongs to the current Shopify store.
- Export the relevant entity from the current store.
- Compare the IDs.
- Replace incorrect IDs where appropriate.
- 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:
- Open the file URL in a browser.
- Confirm that the URL directly provides the file.
- Check whether authentication is required.
- Confirm that the file still exists.
- Verify that the URL has not expired.
- 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:
- Verify the file exists on the server.
- Check the exact file name.
- Check uppercase/lowercase characters.
- Verify the directory/path.
- Confirm that the FTP/SFTP account has read permission.
- 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:
- Verify the server connection.
- Check the destination folder.
- Confirm that the account has write permission.
- Check available server storage.
- Verify the configured server type and credentials.
- 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:
- Check the relevant template documentation.
- Compare the date format with an exported sample.
- Correct invalid dates.
- Avoid unnecessary manual formatting changes.
- 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:
- Identify the affected column.
- Check an exported sample.
- Remove unsupported characters.
- Use the expected numeric format.
- Save and retry the import.
14. Job failed
An import or export job shows a Failed status.
How to troubleshoot:
- Open Migrato → All Jobs.
- Locate the failed job.
- Check the entity and operation.
- Review the input file and selected options.
- Check the job result/error information.
- Identify the failed records or data.
- Correct the source data or configuration.
- Run the job again.
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:
- Open All Jobs.
- Check the job status.
- Review the number of records being processed.
- Check whether other jobs are running.
- Allow the job time to complete.
- 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:
- Open the scheduled job.
- Check the configured Schedule On date.
- Check the configured time.
- Verify the repeat interval, if applicable.
- Check the job in All Jobs.
- Review the current job state.
- 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:
- Review the selected entity.
- Review all applied filters.
- Remove unnecessary filters.
- Run a test export without filters.
- Compare the results.
- 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:
- Review the selected filter.
- Check the filter value.
- Check whether multiple filters are applied.
- Review the date range.
- Remove filters and test again.
- Add filters one at a time to identify which filter excludes the records.
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:
- Open the entity export configuration.
- Select Select Columns.
- Review all available column groups.
- Select the required column.
- Run the export again.
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:
- Open Select Columns for the relevant entity.
- Check whether a Metafield column is available.
- Select the required metafield field.
- Verify the metafield data in the file.
- Check that the metafield definition exists and is supported by the Shopify store.
- 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:
- Verify the source and destination identifiers.
- Check handles and IDs.
- Confirm that referenced records exist.
- Import dependent records before records that reference them when required.
- Review the result file for failed relationships.
- 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:
- Open Plans.
- Check the Limit Per Job for the selected entity.
- Compare it with the number of records in your file.
- Split the data into smaller files if appropriate.
- 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:
- Open the completed import job under All Jobs.
- Download or open the available result file.
- Identify the records that were not imported successfully.
- Review the error information.
- Correct the affected records.
- Create a corrected file.
- Import the corrected records again.
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:
- Open Settings → Notifications.
- Check the configured email addresses.
- Verify that the required event is enabled.
- Check whether the notification is configured for Manual, Scheduled, or both.
- Check the email account's spam/junk folder.
- Verify that the email address is correct.
- 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:
- Open Settings → Job Files Erasure.
- Review the current file-retention setting.
- Check whether older job files have been automatically removed.
- If the file was already deleted, generate a new export or re-upload the required import file.
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. |
28. Recommended troubleshooting process
When an import or export does not work as expected, follow this general process:
- Check the job. Go to Migrato → All Jobs and locate the affected job.
- Check the status. Review whether the job is Processing, Finished, Cancelled, Failed or Queued.
- 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.
- Check the file. For imports, verify the file format, column headers, required data, IDs/handles, dates, numeric values, relationships and duplicate records.
- Check filters. For exports, review the applied filters and remove unnecessary filters to determine whether they are excluding records.
- Check settings. For FTP/SFTP, scheduling, notifications, or file retention issues, review the relevant settings.
- Retry. After correcting the issue, run the import/export again.
- 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 |
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.