ImportKit
Error messages
Every message ImportKit produces, with what caused it and what to do. Most of these mean a guard worked — the app stopped something wrong from reaching your store, per row, and refunded the credit.
Bad rows are reported and skipped; the rest of the file still imports. Errored rows are refunded, so a file with 100 broken rows costs nothing for those 100. The fix-and-re-import loop →
Upload problems
| Message | Cause and fix |
|---|---|
Please upload a .csv file |
The file isn't a .csv. Renaming an .xlsx isn't converting it —
re-export properly. How →
|
This file is over the 50.0 GB upload limit… |
Split the file and import the parts one at a time, or contact support — higher limits and additional files can be arranged. |
This file has more than 1,000,000 rows, which is the limit for a single import. |
Split the file. Rows are independent, so splitting is safe. |
This file has no data rows… |
Only a header row was found. Check you exported the right sheet. |
This file's header row is empty, so there are no columns to map. |
Row 1 is blank. Delete the empty rows above your headers. |
| One enormous column instead of several | Not an error message, but the classic symptom of a semicolon-delimited export from Excel on a European locale. Re-export as CSV UTF-8 (Comma delimited). |
Pre-import check messages
| Message | Cause and fix |
|---|---|
name is required |
A required column is blank on that row. Fill it in or delete the row. |
| Key may only contain letters, numbers, hyphens and underscores | Usually a space, from a display name landing in the key column. Check your mapping if it's on every row. |
ownerType "PRODUCTS_VARIANT" is not valid — did you mean "PRODUCTVARIANT"? |
Take the suggestion. Find and replace across the column. |
| Namespace is reserved by Shopify or an app |
shopify, shopify--, app-- and $app
belong to Shopify and apps. A CSV import creates merchant-owned definitions — pick another
namespace, or leave it blank for custom.
|
| Unrecognised type, with a suggested spelling | Warning, not error The row will still be attempted. Shopify adds types faster than any app can track, so Shopify stays the authority — and if it really was a typo, Shopify rejects the row and refunds the credit. |
duplicate of row 12 |
Two rows share an identity. The first is processed; this one is flagged. Common after concatenating exports or a fill-down going one row too far. More → |
already exists as "single_line_text_field" but this row says "multi_line_text_field" |
Metafield types are immutable in Shopify. Either match the existing type, or create a new definition under a different key. A conflict in every conflict mode. |
This file is too large to preview |
Over 50,000 rows or 32 MB. The import is still allowed, and conflict handling still applies per row — you just don't get the preview. Why → |
Owner and reference problems
| Message | Cause and fix |
|---|---|
No product found matching "merino-crewneck" |
The handle, ID or SKU doesn't exist in this store. Re-export handles from Shopify and match against your file. ImportKit won't create the product. |
More than one product variant has SKU "LIN-SHIRT-M" — use its ID or gid instead |
SKUs aren't unique in Shopify. Use the variant's GID rather than letting the app guess. |
owner_reference "gid://shopify/Customer/1" is not a PRODUCT |
The GID's resource type doesn't match the row's owner_type. Caught before the
write, so the metafield is never applied to the wrong resource. Usually a mis-sorted
spreadsheet.
|
| A page, article or blog handle rejected with a message to use the numeric ID | Shopify has no documented handle lookup for those three, so ImportKit refuses to guess. Get the ID from the admin URL. More → |
custom.written_by: no metaobject entry matches "Jane Do", so it was left out |
Warning, not error The article or entry was still created, without that reference. Check the spelling, or whether the entry is beyond the first 250 of its type. More → |
Definition and type problems
| Message | Cause and fix |
|---|---|
No metafield definition exists yet for PRODUCT custom.store_motto, and no type column was given. |
Shopify needs a type when there's no definition to infer one from. Either import the
definition first — better — or add a
type column.
|
| A warning that a metaobject reference field will accept any metaobject |
The metaobject_reference<author> shorthand couldn't find an
author definition. Import metaobject definitions before metafield definitions.
|
A warning that an $app: prefix was stripped |
App-reserved metaobject types belong to apps. The definition was imported as merchant-owned instead, which is almost certainly what you wanted. |
| A warning about a field type mismatch when updating a metaobject definition | Field types are immutable and entries hold data in them, so Update mode adds new fields only and never rewrites existing ones. Restructuring is admin work. |
Permission problems
| Message | Cause and fix |
|---|---|
CUSTOMER metafields need the "write_customers" access scope, which this app hasn't been granted. |
Not fixable. ImportKit doesn't request customer or order permissions, so those metafields are out of reach by design. Remove those rows. The rest of the file still imports. Why → |
| The same message naming a different owner type and permission | Same cause. The message always names the exact permission that's missing rather than failing vaguely. |
Job-level messages
| Message | Cause and fix |
|---|---|
You have no credits. Buy credits before importing. |
Your balance is zero. Buy a pack in Credits; your file and mapping are still there when you come back. |
Ran out of credits before all rows were imported. Buy more credits and retry to finish. |
The import stopped cleanly at your balance. Nothing was written that couldn't be charged. Buy a pack, then Retry to resume from the first unprocessed row. |
Import was interrupted (server restart). Retry to resume the remaining rows. |
A job stuck for over 15 minutes is marked interrupted. Press Retry; rows that already succeeded are never re-written or re-charged. |
Interrupted while this row was being sent to Shopify, so it may or may not have been
created. It wasn't charged. Check this row in Shopify before importing it again.
|
An uncertain row. Never silently retried and never silently dropped — check that one row in the admin and import it alone if it's missing. More → |
Blog article messages
| Message | Cause and fix |
|---|---|
No title found for this row |
Title is the one genuinely required field for an article. Either the cell is blank or the title column isn't mapped. |
| A warning that a metafield couldn't be set on an article that was otherwise created | The article exists; that one field didn't take. Check the value format for the metafield's type. Value formats → |
Messages that come from Shopify
Some rows pass every ImportKit check and Shopify still rejects them — an unsupported capability for a metafield type, a validation rule that doesn't apply to that type. The message you see is Shopify's own, passed through verbatim rather than flattened into “invalid input”.
Most of Shopify's platform limits are now measured by the pre-import check, so they show up before anything is written. The ones that still reach Shopify are the whole-store ceilings: more than 256 definitions on one owner type, or more than 50 pinned. Those rows are refunded and the rest of the file still imports. Shopify's limits, and what we do and don't catch →
To narrow one down: cut the row back to just the required columns, import it, and add the optional flags back one at a time. Whichever one reintroduces the error is the culprit.
If your message isn't here
Email support@importkit.app with your store domain, the job number from the URL, and the errors CSV attached. Include the row's source data if you can — that's usually enough to answer in one reply.