Common errors
What follows is a triage table for the errors that actually come up in production. If you see something not listed, contact the Graftport team with the run item link and the error text — we’ll add it here.
Source connectivity
| Error / symptom | Likely cause | What to do |
|---|---|---|
401 Unauthorized on extract | Wrong credentials, or admin password rotated. | Update the credential in the migration’s settings. Re-run extract. |
403 Forbidden on a specific resource | The admin user is missing read scope for that resource. | Grant the scope on the source platform; no need to re-issue the credential. |
429 Too Many Requests repeatedly | Source platform’s rate limit hit. | Graftport backs off automatically. If it persists for hours, ask the source platform to raise your limit. |
| Extract hangs at 0 rows | Source API reachable but returning empty pages, often a misconfigured store domain. | Verify the domain in credentials matches what you can browse to. No protocol, no slash. |
Mapping / transform
| Error / symptom | Likely cause | What to do |
|---|---|---|
JSONata error: instance member of … | Mapping references a field that doesn’t exist on this row. | Use field ? field : default in the mapping, or filter out rows where the field is missing. |
JSONata error: cannot evaluate function | Calling a non-existent function (typo, missing $ prefix). | Fix the function name; save creates a new version. |
Output is null for some rows but the source row looks fine | The mapping returns nothing when an early condition fails. | Use the editor’s sample input with that source row to step through. |
| Transform produces unexpected payload but JSONata “looks right” | Pinned mapping version is older than what’s in the editor. | Check the migration’s mapping → version pin. Re-pin and re-transform. |
Destination / Shopify load
| Error / symptom | Likely cause | What to do |
|---|---|---|
Access denied for write_… | Token’s scopes are missing the resource. | Reissue token with the correct scopes; update destination credential. |
handle has already been taken | Slug collision with an existing Shopify product. | Edit the mapping’s handle rule (e.g. add a SKU suffix), re-transform, re-load. |
| Inventory not appearing on the right location | Default mapping assigns to first active location. | Resync locations from the migration page; fork the products mapping if you need per-location split. |
Records load but are Draft instead of Active | Source product status doesn’t map to ACTIVE. | Check the mapping’s status field; default expects enabled. |
Some orders fail with transactions cannot be created on archived order | The destination order already exists from a prior cut-over and got archived. | Switch conflict strategy to skip, or re-create on a fresh destination store. |
Run lifecycle
| Error / symptom | Likely cause | What to do |
|---|---|---|
Run stays in pending for minutes | Worker is busy or down. | Check the platform status page. Don’t queue more runs for the same migration — you’ll just deepen the backlog. |
Run is running but counts don’t move | Run got stuck. | It auto-recovers in most cases; if it doesn’t after several minutes, cancel the run and start a new one — re-running is safe. |
Run is failed but no item shows an error | A startup-time validation failed (e.g. credentials missing). | Look at the run’s top-level error, not the items. Fix the cause; new runs unblock. |
Last updated on