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.
A record loads, but a link to another record is missing — with the warning `reference(s) dropped — target resource not loaded yet`	The record it links to hadn’t reached Shopify yet. Graftport loads the record without the link rather than failing it outright.	Re-run the load. Graftport re-visits exactly the records whose missing link has since arrived and fills it in — you don’t need to re-transform or reset anything. If the warning sticks after a re-run, the linked record isn’t part of the migration; add its resource to the run and load again.
`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.
A collection loads but its image is missing	Shopify couldn’t fetch the collection image (dead source URL, timeout, or the link didn’t resolve to an image). Graftport loads the collection without it rather than failing the whole record.	Check the source image link opens in a browser. If it does, re-run the load; otherwise fix the image in the source and re-run, or set it manually in Shopify.
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	The source stopped responding mid-extract (a hung or very slow endpoint).	Graftport now bounds each source fetch: a stalled extract fails on its own with a “source page fetch exceeded …” error instead of hanging forever, and other resources in the run continue. Check the source is reachable, then re-run — 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.
A finished run, purge, or redirect summary banner stays on the migration page	The banner keeps the last job’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 run, purge, or redirect emission shows its own summary.