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.
`SHOPIFY_BUNDLES_NOT_ENABLED`	The destination store doesn’t have the Shopify Bundles app installed; bundle records can’t load without it.	Install the Shopify Bundles app on the destination store and re-run.
`MISSING_REFERENCE` on a bundle	A bundle product loaded before the products it bundles together; those component products weren’t on the destination yet.	Re-run the load — components load first, so a second pass resolves the bundle. If it persists, the component products are out of scope; include them in the run.
`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.
Staff inboxes flooded with “New order” emails during an order migration	Shopify emails staff a notification for every order Graftport loads.	Disable Settings → Notifications → Staff notifications before the load, re-enable after. See Before migrating orders.

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.
Load shows `succeeded` but 0 loaded right after you stopped a purge	Stopping a purge partway leaves the records past the stop point still loaded and unchanged, so a normal load has nothing new to push.	Graftport now says so on the run — “Nothing to load: N records already loaded and unchanged” — instead of a bare green success. Use Resume purge on the migration to finish clearing those records, or run a Load to re-create the ones the purge already deleted.
After stopping a purge, the summary shows records still loaded	A stopped purge is partial by design — records it already deleted are reloadable, records it hadn’t reached yet are untouched.	The purge summary reports how many records remain loaded and offers Resume purge to finish. Resuming picks up exactly where it stopped.
The “Purge complete” summary banner stays on the migration after it finished	The banner keeps the last purge’s outcome visible until you’ve seen it.	Click the ✕ on the right of the banner to dismiss it. It stays dismissed across reloads; the next purge shows its own summary.

Last updated on June 5, 2026

CLI & AI agent Glossary