Skip to main content

Store Content Error Codes

Error and warning codes for collections, blog posts, pages, menus, redirects, files, and shop settings.

Altera shows a code such as ABC001 with each error or warning. This article explains the codes for this area of the app and how to resolve them. For codes from other areas, see Error and warning codes.

Smart and Manual Collection Codes

Error and warning codes that occur when dealing with smart and manual collections

CLTN001 - Existing Collection is a Smart Collection

The collection that already exists in Shopify is a smart collection, but the import is trying to treat it as a manual collection. Shopify does not allow you to convert a smart collection to a manual collection. You can replace the collection however by setting the 'Command' column to REPLACE.

CLTN002 - Existing Collection is a Manual Collection

The collection that already exists in Shopify is a manual collection, but the import is trying to treat it as a smart collection. Shopify does not allow you to convert a manual collection to a smart collection. You can replace the collection however by setting the 'Command' column to REPLACE.

CLTN003 - Too Many Smart Collection Rules

Shopify does not support more than 60 rules for a smart collection. Your import contains a collection with more than 60 rules, which exceeds Shopify's limit.

How to fix this:

  • Split your collection into multiple smaller collections, each with 60 or fewer rules

  • Consolidate rules where possible (e.g., use a single tag rule instead of multiple individual tag rules)

  • Review your rules to remove any that may be redundant or unnecessary

CLTN004 - Multiple Collections With Same Title

Multiple collections were found with the same title, so the system cannot determine which one to update. Collection titles are not unique in Shopify, so when multiple collections share the same title, you need to use a more specific identifier.

How to fix this:

  • Use the 'ID' column to uniquely identify the collection you want to update

  • Use the 'Handle' column if each collection has a unique handle

  • Export your existing collections first to get the correct IDs or handles

CLTN005 - Unable to Find Metafield Definition

When creating a smart collection rule based on a metafield, the system could not find the corresponding metafield definition. Make sure that the metafield definition exists in your Shopify store, and has the 'Smart collection' enabled, before creating a smart collection rule that references it.

CLTN006 - Invalid Metafield Condition Format

The metafield condition column format is invalid. When creating a smart collection rule based on a metafield, the column must follow the correct format:

  • For product metafields: Metafield: namespace.key

  • For variant metafields: Variant Metafield:namespace.key

For example: Metafield: custom.size or Variant Metafield: custom.color

Make sure your metafield condition includes the namespace and key separated by a period (.).

For more information about smart collection rule formats, see the Smart Collection Fields documentation.

CLTN007 - Product Not Found

The product specified in your import could not be found on the store. When linking products to a manual collection, the system first tries to find the product by ID, then falls back to the handle. If neither works, this warning is shown and the product is not added to the collection.

How to fix this:

  • Verify the product exists on your store

  • Check that the product ID or handle is correct

  • Export your products first to get the correct IDs and handles

  • If the product was deleted, remove it from your import file or recreate the product first

CLTN009 - Collection Source Data Skipped

Part of a collection's source definition in a Collections import (or the Must Match value in a Smart Collections import) could not be applied and was skipped. This happens when a row uses something the current import can't represent yet (for example a variant price/weight/inventory rule or a metafield rule), when a referenced product, variant, or collection could not be resolved to build a source, or when the row points at a source that belongs to another app.

Rules you create in the Shopify admin are yours to edit, and Altera imports them normally. A source is only left unchanged when it is a shared source, which one app owns and several collections can reuse, so changing it would affect collections outside your file.

How to fix this:

  • Check the flagged rows for rule columns that aren't yet supported on the Collections type, and set that membership on the collection another way

  • Check the Inclusion: Type (Rule: Mode) value. Only Include and Exclude are recognized; a row with any other value is skipped so that a typo can't turn an exclude rule into an include rule

  • A rule cell the import cannot apply at all (a relation the field does not take, an exclude rule on a field exclusions don't support, an unknown Inclusion: Match, a metafield definition or category that does not exist) fails the whole row instead; see CLTN024

  • On a collection REPLACE (or a new collection), a source block whose Source Command is DELETE or IGNORE has nothing to act on and is skipped. Remove the stray command cell if you meant to create that source

  • Verify that any Product: ID / Product: Handle / Rule: Condition values reference items that exist on the store

  • A sub-collection or Collection rule reference that is a number is matched as a collection ID first and then as a handle, so a collection with a numeric handle (for example 2024) can be referenced by that handle. The reference is skipped when neither a matching ID nor a matching handle exists

  • For a shared source, edit it in the app that owns it, or remove the Source ID value and let Altera create a separate source for this collection

  • Export the collection again to see the exact columns Altera produces

CLTN010 - Collection Title Required

A new collection can't be created without a Title. The row had no existing collection to update and no Title to create one.

How to fix this:

  • Add a Title for the collection, or

  • Include an ID or Handle that matches an existing collection if you meant to update it

CLTN011 - Collection Not Found for Update

A row used the UPDATE command but no existing collection matched its ID, Handle, or Title.

How to fix this:

  • Confirm the identifier matches a collection on the store (export collections to get exact IDs and handles)

  • Use MERGE or NEW instead if you want the collection created when it doesn't exist

CLTN012 - Collection Source Ambiguous

A Collections import couldn't tell which of the collection's sources the rows belong to, because several sources on the collection share the title used in the Source: Title (Source) column. Rows without a Source: ID or Source: Title never raise this: they edit the first existing source with the same Source: Type.

How to fix this:

  • Export the collection with the Collections data type and edit that file - it includes the Source: ID column that identifies each source

  • Or give the sources different titles in the Shopify admin and use those in the Source: Title column

CLTN013 - Collection Source Not Found

A row used the UPDATE Source Command but no existing source on the collection matched its Source ID or Source title.

How to fix this:

  • Export the collection with the Collections data type to get the current source names and IDs

  • Use MERGE (or leave Source Command blank) if you want the source created when it doesn't exist

CLTN014 - Shopify Did Not Accept the Collection Sources

Shopify rejected the collection's sources without reporting a reason, so the collection row could not be imported. The app sends the collection's rules and product/variant selections to Shopify as "sources", and in rare cases Shopify declines the write silently instead of returning an error message.

How to fix this:

  • Retry the import - transient Shopify issues can cause this

  • Check the collection in your Shopify admin to confirm whether any of the row's changes were applied

  • If the error happens repeatedly for the same rows, contact support with the Job ID so we can investigate the exact input

CLTN015 - Collection Skipped From Export

A collection was left out of a Smart Collections or Manual Collections export because it uses Shopify's newer collection features that those formats can't represent. This includes collections with more than one source, exclusion rules, sub-collection membership, variant-level membership, shared sources, or a source that mixes rules with hand-picked products.

The collection still exists on your store and its data is intact. It just can't be expressed in the legacy Smart or Manual layout.

How to fix this:

  • Export the flagged collections with the Collections data type instead, which supports all of Shopify's newer collection features

  • If you believe the collection is a plain smart or manual collection and should have been included, contact support with the Job ID

CLTN016 - Collection Rules Not Fully Exported

Some of a collection's rules could not be written to the export file, so the collection's rows are incomplete. This happens when a rule uses a condition type or combination the export format can't express yet, for example a new Shopify condition type, or a multi-value Category rule that mixes Include Descendants settings between its values. Multi-value conditions whose own any/all setting differs from the source's export as a single row using the Rule: Match Type column and are not affected.

Be careful about re-importing this file with the REPLACE command: because the affected rules are missing from the file, a REPLACE import could remove them from the collection.

How to fix this:

  • Review the flagged collection in your Shopify admin to see the full rule set

  • Avoid REPLACE imports of the flagged collection from this file; use targeted updates instead

  • Contact support with the Job ID if you need the missing condition type supported

CLTN017 - Collection Products Not Fully Exported

A collection holds more manually selected products than could be read, so some of its products are missing from the export file. Collections normally export every manually selected product, however many there are. This warning means reading the full list stopped early, usually because the collection was being edited during the export or Shopify stopped returning results partway through.

Be careful about re-importing this file with the REPLACE command: because the missing products aren't in the file, a REPLACE import could remove them from the collection.

How to fix this:

  • Run the export again, ideally when the collection isn't being edited

  • Avoid REPLACE imports of the flagged collection from this file; use MERGE instead, which leaves products that aren't in the file alone

  • Contact support with the Job ID if the same collection keeps being flagged

CLTN018 - Shopify Rejected Removing the Collection's Last Source

Shopify rejected removing the collection's last remaining source, so the collection was left unchanged.

Normally, deleting a collection's last source works: Shopify accepts a collection with zero sources, so a Source Command of DELETE on every source is the standard way to empty a collection. This error appears only when Shopify refuses that write, which can happen if Shopify brings back its earlier rule that every collection must keep at least one source.

How to fix this:

  • To empty the collection, use the collection Command REPLACE with a single rule that matches no products. For example, set Rule: Product Column to Tag, Rule: Relation to Equals, and Rule: Condition to a tag no product uses. The collection then stays in place with zero products

  • To swap the source for a different one, put the replacement source's rows in the same file. The delete and the new source are applied together, so the collection is never left without a source

  • To remove the collection entirely, use the collection Command DELETE instead

CLTN019 - Duplicate Collection Source Blocks Combined

A Collections import file contained more than one block of rows with the same Source title (or Source ID) for one collection, with other rows in between. Altera combined the blocks into a single source, the same way it treats same-titled rows that sit next to each other. Without this, the import would either create two sources with the same title or fail the row when updating an existing collection.

The warning names the duplicated source title so you can find the affected rows.

How to fix this:

  • Check the combined source on the collection to confirm the merged rules and product selections are what you intended

  • If the blocks were meant to be different sources, give each block a unique Source title and import again

  • To avoid the warning, keep all rows for one source together in the file

CLTN020 - Collection Handle Changed

An import row matched an existing collection by its ID, and the row's Handle column contained a different handle, so the collection was renamed to the new handle. This is an informational message, not an error: providing a new handle on an ID-matched row is how you intentionally rename a collection's handle.

Renaming a handle changes the collection's storefront URL, so links to the old URL stop working unless you set up a redirect.

How to fix this:

  • If the rename was intentional, no action is needed

  • If the rename was not intended, re-import the row with the collection's original handle in the Handle column

  • Consider creating a URL redirect from the old collection URL to the new one so existing links keep working

CLTN021 - Collection Not Found for Delete

A row used the DELETE command but no existing collection matched its ID, Handle, or Title, so there was nothing to delete.

How to fix this:

  • Confirm the identifier matches a collection on the store (export collections to get exact IDs and handles)

  • Remove the row if the collection was already deleted

CLTN022 - Collection Sort Order Not Recognized

The Sort Order cell holds a value that is not one of the sort orders Shopify supports, so the row was not imported.

How to fix this:

  • Use one of: Alphabet, Alphabet Descending, Best Selling, Created, Created Descending, Manual, Most Relevant, Price, Price Descending

  • Leave the cell blank to keep the collection's current sort order (a new collection is created as Best Selling)

CLTN023 - Collection Deleted but Replacement Failed

The row used the REPLACE command, which deletes the existing collection and creates a new one from the row. The delete succeeded, but Shopify rejected the new collection, so the collection is no longer on the store.

Before it deletes, Altera checks the row for problems it can detect itself (a missing title, invalid rule conditions, and so on) and fails the row with the collection intact. This error only appears when Shopify rejects something after the delete.

To resolve this, fix the problem in the message and import the row again with Command set to MERGE, which creates the collection if it is missing. The original collection's ID is gone, so anything that referenced it by ID needs to be linked again.

CLTN024 - Collection Rule Cell Not Valid

A cell in the source or condition columns holds a value the import cannot apply, so the collection row was not imported. Nothing on the collection changes, the same way Matrixify fails such a row. Importing the rest of the rules would build a collection that matches a different set of products from the one the file describes. The message names the cell and, where there is a fixed list, the acceptable values. This covers:

  • A Source: Type, Condition: Field, Condition: Relation, or Inclusion: Match value the Collections sheet does not define

  • A relation the field does not take (for example Price with Greater than or equal to, or Tag with Contains)

  • An exclude rule (Inclusion: Type = Exclude) on a field exclusions don't support (only Tag, Type, Vendor, Category, Category with Subcategories, and Collection can exclude)

  • A Collection rule on the include side (use a Collections source to pull products in)

  • A metafield rule whose definition does not exist, or whose definition does not have the Smart collection condition capability turned on

  • A Category value that is not in the Shopify product taxonomy

  • A Price, Compare at price, Inventory stock, or Weight value that is not a single number (a comma makes the cell a list)

How to fix this:

  • Use the spellings from an export of your collections (for example Products, Tag, Includes, Does not equal)

  • Check for a typo or a value copied from another column

  • For metafield rules, create the definition in the Shopify admin under Settings > Custom data and turn on Smart collection condition for it

  • For category rules, export a collection that uses the category to copy its aa-1 | Breadcrumb value

CLTN025 - Collection Redirect After Handle Change

Reports the URL redirect written after an import changed a collection's handle (a row matched by ID with a different Handle). As an info message it names the redirect that was created from the old collection URL to the new one; as a warning it means the redirect could not be created and the old URL no longer resolves.

How to fix this:

  • Create the redirect from /collections/<old-handle> to /collections/<new-handle> with a Redirects import, or leave it if the old URL is not linked anywhere

  • Turn off "Create redirects on handle change" in the import options if you do not want redirects

CLTN026 - Collection Publish Date Not Valid

A Published At: <channel> cell holds a value that is not a date (for example next week), so the collection row was not imported. Publishing the collection right away would be a guess, and Matrixify fails such a row too.

How to fix this:

  • Write the date as 2026-12-24 09:30 or as an ISO timestamp such as 2026-12-24T09:30:00-05:00

  • A date without an offset is read in the shop's timezone

  • Leave the cell blank to publish right away, or clear the Published: cell to unpublish

CLTN027 - Collection Image Not Saved

Shopify could not load the image from the Image Src URL (the link does not exist or is not reachable), so the collection was saved without it. The rest of the row was imported.

How to fix this:

  • Check that the URL opens in a browser and points straight at an image file

  • Upload the image to Shopify (Content > Files) and use the Shopify CDN link instead

  • Import the row again once the URL works; only the image is missing

Blog Post Codes

These codes are related to uploading blog posts (articles) and blogs.

BLG001 - Invalid Image URL

The image for a blog post needs to be a complete URL that starts with http:// or https://.

BLG002 - No Blog On The Store

A new article row didn't specify a blog (no 'Blog: ID', 'Blog: Handle', or 'Blog: Title') and your store has no blogs at all, so the article can't be attached anywhere. Create a blog on your store (or add a 'Blog: Title' column to your import file with the blog title you want to use) and re-run the import.

BLG003 - Only One Image URL Supported

Shopify blog posts only support one featured image, but you can include additional images in the body HTML of your post. This warning is raised if there's commas or pipe characters in the Image Src column because those are often used to separate different URLs.

BLG004 - Published Date Before 1970

Shopify does not accept blog post dates before January 1, 1970 (the Unix epoch). If you have blog posts with dates before this, you'll need to update them to a valid date range. This limitation is due to how Shopify handles date storage internally.

BLG005 - Published Date Too Far in Future

The published date is more than 10 years in the future, which might indicate a data entry error. While Shopify may accept future dates, having dates too far in the future could cause unexpected behavior or indicate that the year was entered incorrectly (e.g., typing 2224 instead of 2024).

BLG006 - Invalid Published Date Format

The 'Published At' column contains a value that cannot be parsed as a valid date/time. The date should be in a standard format that can be recognized, such as:

  • 2024-01-15

  • 2024-01-15 14:30:00

  • Jan 15, 2024 2:30 PM

  • 2024/01/15

Make sure all values in the 'Published At' column are either empty (for drafts) or contain properly formatted date/time values.

BLG007 - Body HTML Truncated by Excel

This code has been replaced by IMP007.

BLG008 - Multiple Blogs With Same Title

Multiple blogs were found with the same title, so the system cannot determine which one to update. Blog titles are not unique in Shopify, so when multiple blogs share the same title, you need to use a more specific identifier.

How to fix this:

  • Use the 'Blog: ID' column to uniquely identify the blog you want to update

  • Use the 'Blog: Handle' column if each blog has a unique handle

  • Export your existing blogs first to get the correct IDs or handles

BLG009 - Multiple Articles Found

The 'Handle' or 'Title' you provided matches more than one article on your store. Shopify allows the same article handle to be used in different blogs, so when an article handle (or title) is not unique on its own, you need to tell the import which blog the article lives in.

How to fix this:

  • Use the 'ID' column to uniquely identify the article you want to update

  • Add a 'Blog: ID', 'Blog: Handle', or 'Blog: Title' column so the import knows which blog the article belongs to

  • Export your existing blog posts first to get the correct IDs

BLG010 - Blog Title Required to Create Blog

A row referenced a blog that doesn't exist on your store yet (for example, by 'Blog: Handle' only) but didn't provide a 'Blog: Title'. Shopify requires a title to create a new blog, so the article can't be imported.

How to fix this:

  • Add a 'Blog: Title' value for the row so the new blog can be created

  • Or change the 'Blog: Handle' / 'Blog: ID' to reference an existing blog on your store

  • Export your existing blogs first to confirm the correct handle or ID

BLG011 - Article Title Required to Replace

The row used the REPLACE command, which deletes the existing article and creates a new one from the row. The row has no Title value, and Shopify requires a title to create an article, so the row failed before anything was deleted. The existing article is unchanged.

How to fix this:

  • Add a Title value to the row and import it again

  • To update the existing article without re-creating it, use MERGE or UPDATE instead

BLG012 - Article Deleted but Replacement Failed

The row used the REPLACE command, which deletes the existing article and creates a new one from the row. The delete succeeded, but Shopify rejected the new article, so the article is no longer on the store.

Before it deletes, Altera checks the row for problems it can detect itself (a missing title, a truncated body, an invalid published date, and so on) and fails the row with the article intact. This error only appears when Shopify rejects something after the delete.

To resolve this, fix the problem in the message and import the row again with Command set to MERGE, which creates the article if it is missing. The original article's ID is gone, so links that used the article ID need to be updated.

Page Codes

Error codes that occur when importing pages.

PAGE001 - Page Title Required to Replace

The row used the REPLACE command, which deletes the existing page and creates a new one from the row. The row has no Title value, and Shopify requires a title to create a page, so the row failed before anything was deleted. The existing page is unchanged.

How to fix this:

  • Add a Title value to the row and import it again

  • To update the existing page without re-creating it, use MERGE or UPDATE instead

PAGE002 - Page Deleted but Replacement Failed

The row used the REPLACE command, which deletes the existing page and creates a new one from the row. The delete succeeded, but Shopify rejected the new page, so the page is no longer on the store.

Before it deletes, Altera checks the row for problems it can detect itself (a missing title, a truncated body, and so on) and fails the row with the page intact. This error only appears when Shopify rejects something after the delete.

To resolve this, fix the problem in the message and import the row again with Command set to MERGE, which creates the page if it is missing. The original page's ID is gone, so navigation links that used the page ID need to be updated.

Menu Codes

Error and warning codes for importing and exporting menus.

When you import menus you need to have menu item columns like "Menu Item: Resource Type" and "Menu Item: Title". To get these columns in an export, make sure that you select the 'General' and 'Menu items' groups when configuring which fields to export.

The Shopify API rejected the menu data and refused to save it. This typically occurs when the menu configuration violates Shopify's business rules or contains invalid data that passed initial validation but failed at the API level.

The 'Menu Item: Title' column contains empty values. When importing menus, every menu item must have a title. Check your spreadsheet and ensure that all rows with menu items have a title specified in the 'Menu Item: Title' column. Empty titles will prevent the menu items from being created properly in Shopify.

The menu title is required when creating a new menu. Make sure your import includes the 'Title' column with a valid menu name for each menu you want to create. Empty or missing titles will prevent the menu from being created in Shopify.

A circular reference has been detected in your menu structure. This occurs when a menu item is configured to be its own parent or ancestor, creating an infinite loop in the menu hierarchy.

Common scenarios that cause this error:

  1. Direct circular reference: A menu item has itself as its parent

  2. Indirect circular reference: Menu Item A → Menu Item B → Menu Item A

  3. Multi-level circular reference: Menu Item A → Menu Item B → Menu Item C → Menu Item A

How to fix this:

  • Review your menu structure and ensure no menu item references itself as a parent

  • Check that parent-child relationships form a proper tree structure (no loops)

  • Verify that menu items don't have circular parent relationships across multiple levels

  • Use the 'Menu Item: Parent ID' or 'Menu Item: Parent Title' columns carefully to avoid creating loops

Example of problematic data:

Menu Item: Title | Menu Item: Parent Title
Home            |
About           | Home
Contact         | About
Home            | Contact  ← This creates a circular reference

To resolve this, ensure your menu hierarchy flows in one direction without any item becoming its own ancestor.

A menu item has the same value for both 'Menu Item: ID' and 'Menu Item: Parent ID', which creates a direct self-reference. A menu item cannot be its own parent in the menu hierarchy.

This is a specific case of a circular reference where a menu item directly references itself as its parent, rather than indirectly through other menu items.

How to fix this:

  • Check the row indicated in the error message

  • Ensure that 'Menu Item: ID' and 'Menu Item: Parent ID' have different values

  • If the menu item should be a top-level item (no parent), leave 'Menu Item: Parent ID' empty

  • If the menu item should have a parent, provide the correct parent ID

Example of problematic data:

Menu Item: ID | Menu Item: Parent ID | Menu Item: Title
123          | 123                  | Products      ← Cannot be its own parent

Corrected data:

Menu Item: ID | Menu Item: Parent ID | Menu Item: Title
123          |                      | Products      ← Top-level item (no parent)

or

Menu Item: ID | Menu Item: Parent ID | Menu Item: Title
123          | 456                  | Products      ← Has different parent

A menu item references a resource by handle (in the 'Menu Item: Resource Handle' column) but Altera could not find a matching resource in your Shopify store. The menu item was imported but its resource link was removed - the item's type was set to HTTP with a placeholder URL of #.

Common causes:

  • The resource handle contains a typo (e.g., my-produc instead of my-product)

  • The referenced resource (page, collection, product, blog, etc.) does not exist in your store

  • The resource was deleted after the spreadsheet was exported

How to fix this:

  • Verify the handle in the 'Menu Item: Resource Handle' column matches an existing resource in your store

  • If the resource was deleted, either recreate it or update the menu item to use a direct URL instead

  • Re-import the corrected spreadsheet to update the menu item's resource link

The row used the REPLACE command, which deletes the existing menu and creates a new one from the row. The delete succeeded, but Shopify rejected the new menu, so the menu is no longer on the store.

Before it deletes, Altera checks the row for problems it can detect itself (a missing menu title, empty item titles, circular item references, and so on) and fails the row with the menu intact. This error only appears when Shopify rejects something after the delete.

To resolve this, fix the problem in the message and import the rows again with Command set to MERGE, which creates the menu if it is missing. The original menu's ID is gone, so theme settings that referenced it by handle usually keep working, but anything that referenced it by ID needs to be linked again.

Redirect Codes

Error codes that occur when importing URL redirects.

REDR001 - Redirect Path and Target Required

The row used the REPLACE command, which deletes the existing redirect and creates a new one from the row. The row is missing a Path or Target value, and Shopify requires both to create a redirect, so the row failed before anything was deleted. The existing redirect is unchanged.

How to fix this:

  • Add the missing Path or Target value to the row and import it again

  • To update the existing redirect without re-creating it, use MERGE or UPDATE instead

REDR002 - Redirect Deleted but Replacement Failed

The row used the REPLACE command, which deletes the existing redirect and creates a new one from the row. The delete succeeded, but Shopify rejected the new redirect, so the redirect is no longer on the store.

Altera validates the row before it deletes, so this error only appears when Shopify rejects something after the delete, for example a target URL Shopify considers invalid.

To resolve this, fix the problem in the message and import the row again with Command set to MERGE, which creates the redirect if it is missing.

File Codes

Error and warning codes for importing and exporting files.

FILE001 - Shopify Trial Limitation

In some situations stores that are on a Shopify Trial are not able to upload files through the API. This is related to the store's subscription to Shopify, it has nothing to do with being on a paid or free plan with Altera. If your files fail to upload you will need to either switch to a paid Shopify plan or reach out to Shopify support for more help. In some situations this also applies to uploading images when you create new products.

FILE003 - File Already Exists

A row used the NEW command, but a file with the same ID or filename already exists on the store, and the row had no Alt or Filename value to update. The NEW command only creates files, so the row was skipped and the existing file was left unchanged.

How to fix this:

  • To update the existing file's alt text or filename, include an Alt or Filename value in the row

  • To replace the file itself, use the REPLACE command

  • To create a separate file, upload it with a different filename

FILE005 - Alt Text Required for Updates

The UPDATE command changes a file's alt text, so the file needs an Alt Text column. A blank cell in that column clears the alt text; a missing column leaves nothing to update. If you want to replace the file entirely rather than just updating its metadata, use the REPLACE command instead.

FILE006 - Failed to Stage Media File

The system failed to download and stage the media file for upload to Shopify. This error occurs when importing VIDEO or 3D model files (MODEL_3D) that need to be staged before uploading to Shopify's servers.

Media types are automatically detected from file extensions when not explicitly specified:

  • Video files: .mp4, .mov, .webm

  • 3D model files: .glb, .usdz

Common reasons for this error include:

  • The source URL is not accessible or returns a 404 error

  • Network connectivity issues during file download

  • The file download timed out

  • The file is empty or corrupted

  • Shopify refused the upload. The row message includes Shopify's reason, for example You can't upload more than 200 videos in an hour. Shopify limits each store to 200 video uploads per hour.

  • Issues with Shopify's staging upload service

How to fix this:

  • Verify that the media file URL is accessible and returns a valid file

  • Check that the file exists at the specified URL

  • Ensure the file is a valid VIDEO or 3D model file

  • Try again later if there are temporary network or service issues

  • If Shopify refused the upload because of the 200 videos per hour limit, wait an hour and import the same file again with the MERGE command. Files that already exist on the store are matched by file name and only their alt text is updated, and the missing videos are uploaded. Keep each video import to 200 videos or fewer and leave an hour between imports.

  • If the problem persists, try downloading the file manually to verify it's accessible

Note: IMAGE and EXTERNAL_VIDEO media types do not require staging and are uploaded directly.

FILE007 - Alt Text Over 512-Character Limit

One or more alt text values in your file are over Shopify's 512-character limit. These values will be rejected by Shopify during import.

This commonly happens with programmatically generated alt text, such as URL-encoded filenames used as alt text.

To fix this: Shorten the alt text values in your spreadsheet to 512 characters or fewer before importing.

FILE008 - File Link Required to Replace

The row used the REPLACE command, which deletes the existing file and uploads a new one from the row's Link URL. The row has no Link value, so there is nothing to upload and the existing file was left in place.

How to fix this:

  • Add a Link column with a publicly accessible URL for the new file, then import the row again

  • To rename a file or change its alt text without re-uploading it, use MERGE or UPDATE instead

FILE009 - File Deleted but Replacement Failed

The row used the REPLACE command, which deletes the existing file and uploads a new one from the row's Link URL. The delete succeeded, but Shopify rejected the new file, so the file is no longer on the store.

Before it deletes, Altera validates the row and stages the new media, so an unreachable or invalid source fails the row with the file intact. This error only appears when Shopify rejects something after the delete.

To resolve this, fix the problem in the message and import the row again with Command set to MERGE, which uploads the file if it is missing. The original file's ID and CDN URL are gone, so anything that referenced them needs to be updated.

FILE010 - File Link Not Usable for Replace

The row used the REPLACE command, which deletes the existing file and uploads a new one from the row's Link URL. The Link failed the pre-delete check, so nothing was deleted and the existing file is unchanged. The message says which check failed:

  • The Link points at the file being replaced: the URL is the existing file's own CDN URL, which stops working when the file is deleted. This usually happens when re-importing the store's own file export with REPLACE.

  • The Link could not be reached, or returned HTTP 404/410: the URL does not resolve or the file is gone from the source.

How to fix this:

  • Host the new file at a URL that is not the file's own CDN URL, and check that the URL opens in a browser

  • To keep the existing file and only change its name or alt text, use MERGE or UPDATE instead

Note: hosts that block automated clients can pass this check and still fail when Shopify fetches the file; that case is reported as FILE009.

Shop Codes

Error codes for the Shop import, which updates the store's own metafields. A store has exactly one shop record, so MERGE is the only command that works.

SHP001 - Cannot Create a Shop

A row in the Shop sheet used the NEW command. A store always has exactly one shop record, so a new one cannot be created. Change the command to MERGE to update the store's metafields.

SHP002 - Cannot Delete the Shop

A row in the Shop sheet used the DELETE command. The shop record cannot be deleted. To remove individual shop metafields, see the Metafields guide.

SHP003 - Cannot Replace the Shop

A row in the Shop sheet used the REPLACE command. The shop record cannot be deleted and recreated. Change the command to MERGE to update the store's metafields.

SHP004 - Cannot Update the Shop

A row in the Shop sheet used the UPDATE command, which is not supported for the shop record. Change the command to MERGE to update the store's metafields.

Related Articles
Did this answer your question?