Why are some variants not showing on my Shopify product page?
Short answer: A variant that exists in your admin but never appears on the product page is usually hidden by one of six things: your theme’s sold-out handling, product status, an invisible character in an option value, the three option ceiling, Liquid’s 250 variant ceiling, or channel publishing. Rubik Variant Images, built by Craftshift, hides or disables sold-out swatches.
You added twelve variants. The product page shows nine. Nothing errored, nothing warned you, and the three that vanished are not obviously different from the nine that did not. This is one of those Shopify problems where the fix takes two minutes and finding it takes two hours, purely because the platform has no reason to tell you which of six unrelated systems swallowed your variant.
So below is a diagnostic order rather than a list. Cheapest check first, most expensive last, and a source for every claim about how Shopify behaves. Where I could not find documentation, I say so instead of guessing, because a confident wrong answer here costs you an afternoon.
One thing to get out of the way first. Most of the causes below are data or theme problems, and no app fixes them. We build variant apps and I would still rather you spend ten minutes in the admin than install anything.
In this post
- Step 1: does the variant exist at all?
- Step 2: what your theme does with sold-out combinations
- Step 3: product status and sales channel publishing
- Step 4: two option values that look identical
- Step 5: the three option ceiling
- Step 6: the 250 variant rendering ceiling
- Step 7: when it only happens on one sales channel
- What I could not confirm
- Frequently asked questions
Step 1: does the variant exist at all?
Thirty seconds, and it eliminates about a third of cases. Open the product in the admin and count the rows in the variant table. Not the option values. The actual variant rows.
Adding an option value does not always create every combination of it. If you added Green to a Colour option on a product that already had Small, Medium and Large, you may have three new variants, or one, or none, depending on how you added it. A picker can render an option value that maps to no variant at all, and Shopify’s theme documentation is explicit about what happens then: “If the option value combination maps to a variant that is not present, the requested option values will be selected but the product fields selected_variant and selected_or_first_available_variant will return null.”
Null. Not an error, not a warning. The theme just has nothing to show, and what you see depends entirely on how the theme author handled a case they may not have thought about.
Step 2: what your theme does with sold-out combinations
This is the single most common cause, and it is the one people never suspect, because they think of it as an inventory setting rather than a display setting.
Shopify hands themes the raw availability data and then gets out of the way. Liquid’s variant.available is documented as “Returns true if the variant is available. Returns false if not.” The product_option_value object carries its own available flag, described as whether the option value is available in the context of the values currently selected for the other options. That is everything a theme needs to decide what to do with a sold-out combination.
And what Shopify tells theme developers to do with it is: your call. Their variant documentation recommends “that you present each of these options separately in the UI” and then points developers at Dawn’s implementation files for a practical example. There is no prescribed behaviour for unavailable combinations anywhere in that document. No required setting, no required label. Which is exactly why the setting is called something different in every theme you have ever used.
Go to Online Store, Customize, open a product template, and click the variant picker block. Look for anything with the word unavailable, sold out, or out of stock in it. Many themes ship a checkbox along the lines of “Hide unavailable product variants”, and when it is on, a variant with zero inventory and a Deny policy is simply not rendered. We covered the four ways to control this, ranked by how much they can break, in how to hide unavailable variants on Shopify.
Fastest way to prove it is the cause: set the inventory policy on one missing variant to continue selling when out of stock, reload the storefront, and see whether it comes back. If it does, you are done. Change the theme setting or restock, and nothing else in this post applies to you.
There is a real design argument buried here that most stores get wrong. Hiding sold-out variants entirely tells a shopper nothing. Showing them struck through tells them the size exists and to check back. We wrote up the tradeoff in how to handle out of stock variants on Shopify, and for once the ugly option is usually the better one.
Step 3: product status and sales channel publishing
If the whole product is missing rather than a few variants, this is your answer, and Shopify’s API documentation defines the three states precisely:
| Status | Shopify’s documented definition |
|---|---|
| ACTIVE | “The product is ready to sell and can be published to sales channels and apps.” |
| DRAFT | “The product isn’t ready to sell and is unavailable to customers on sales channels and apps.” |
| ARCHIVED | “The product is no longer being sold and isn’t available to customers on sales channels and apps.” |
Read the ACTIVE definition again, because it is the one that catches people. It says the product can be published. Not that it is. Active plus not published to the Online Store is a completely normal state, and it produces a product that looks fine in the admin and does not exist on your storefront. Check the Sales channels box on the product page, not just the status dropdown. If you are working through a catalog where this has happened at scale, our note on Shopify’s unlisted product status covers the neighbouring cases.
Archived is the nastier one, because archiving is often done in bulk by somebody tidying up, and it is not reversible by accident. If a colour disappeared from a group of linked products, archived is where I would look second.
Step 4: two option values that look identical
Look at your Colour option and count the values. If Navy is in there twice, or if you have eleven values where you expected ten, you have found it.
Shopify does reject exact duplicates. The Admin API documents a user error OPTION_VALUE_ALREADY_EXISTS with the message “Option value already exists.” So if two values that look the same both got saved, they are not the same. Something invisible is different between them: a trailing space, a non-breaking space pasted from a spreadsheet, a Turkish dotless i, a Cyrillic character that renders identically to a Latin one.
The effect is worse than a duplicate row. Half your variants get attached to Navy and half to Navy , the picker renders what looks like one value, and clicking it only reaches one of the two sets. Variants missing, no error, nothing visibly wrong in the admin.
How to catch it: click into the option value field and press End. If the cursor lands past the last letter, there is a space. Or export the product to CSV and open it somewhere that will show you the raw cell. This is overwhelmingly a CSV import problem, so if you imported this catalog, run the file through our free Shopify CSV validator before you import the next one. Getting option value naming right up front is cheaper than fixing it after, which is why we wrote a whole post on choosing Shopify variant option names.
Step 5: the three option ceiling
Shopify’s help documentation is unambiguous: “Each product can have up to three options. The options can be different from product to product.” The Admin API backs it with an error code, OPTIONS_OVER_LIMIT, whose message reads “Can only specify a maximum of 3 options”. The same help page states “You can create up to 2,048 variants for a product.”
Three. Not four. So Colour, Size, Material fills your budget and Length has nowhere to go, and what happens next is that somebody encodes the fourth axis into the third one as “Cotton / 32 inch”. It works, sort of, until the day it does not, and it is the reason a lot of “some variants are missing” reports turn out to be “some variants were never created because there was no room for them”.
Two honest ways out. Rebuild the catalog so each value of the fourth axis becomes its own product, or link separate products together so the group itself carries an extra axis on top of each product’s own three options. The second is what combined listings are for, and it is also how stores get past the per-product variant ceiling without moving to Plus. We ranked the options in Shopify 3 option type limit workarounds, and the arithmetic for whether you will hit the ceiling at all is in our free variant combination calculator.
Once the data is right, the display problem is the one left over, and that is where an app earns its place rather than papering over a mistake. Rubik Variant Images gives every variant its own media set and lets you hide or disable sold-out swatches on purpose rather than as a side effect of a theme checkbox you did not know existed. Free to install, 5.0 stars across 420 reviews.
“We also sell a lot of one-of-a-kind variants (stock of 1 item per variant), so sometimes we have 20 variants for a given product. […] Now with Rubik, we hide all unavailable variants AND their thumbnails both at once.”
The Amma Shop, US, via Rubik Variant Images on the Shopify App Store
Step 6: the 250 variant rendering ceiling
This one almost nobody knows, and it explains the weirdest version of the symptom: a product where roughly the first 250 variants work and everything after that is gone.
Liquid’s product.variants property is documented with a hard note attached: it “Returns a maximum of 250 variants when unpaginated.” The recommended fix is the paginate tag, with a documented maximum of 50 variants per page.
Put the two Shopify numbers next to each other and the gap is obvious. You are allowed 2,048 variants on a product. A theme that loops over product.variants without paginating sees 250 of them. That is not a bug in your theme so much as a limit almost no theme author has had to think about, because almost no product needs it.
Should you build a product with 900 variants? No. Almost never. A shopper cannot find anything in a picker that size, the admin becomes painful, and you are one theme update away from this exact problem. Splitting into separate linked products is a better answer at that scale for reasons that have nothing to do with limits, starting with the fact that each colour gets its own URL and its own images. There is a fuller argument in how to bypass the Shopify variant limit without Plus and in the 2,048 variant limit explained.
Step 7: when it only happens on one sales channel
Different symptom, different cause. If the variant shows on your Online Store but is missing from a marketplace feed, a point of sale terminal, or a wholesale catalog, stop looking at your theme.
Publication in Shopify is modelled at the variant level, not only the product level. The Admin API’s ProductVariant object exposes publishedOnPublication (“Whether the resource is published to a specified publication”), resourcePublications, unpublishedPublications (“The list of publications that the resource isn’t published to”) and availablePublicationsCount. There is also sellableOnlineQuantity, “The total sellable quantity of the variant for online channels”.
So a channel or catalog app can absolutely leave one variant out while keeping the rest. When a variant is missing on exactly one channel, the thing that owns that channel’s catalog is the thing to interrogate, and that is usually an app rather than Shopify.
What I could not confirm
Three things I looked for and did not find in Shopify’s public documentation. I am listing them rather than filling the gaps with a plausible guess.
- Whether Shopify trims whitespace on option values. The
OPTION_VALUE_ALREADY_EXISTSerror proves exact duplicates are rejected. What counts as exact is not documented. Test it on a scratch product before you rely on either answer. - A merchant-facing control for unpublishing a single variant from the Online Store. The variant level publication fields exist in the Admin API, but I found no documented admin screen that exposes them for the Online Store channel.
- The exact setting name in current Dawn. I could not find an unavailable-variant setting in the section schema I checked, and theme code changes between releases. Look in your own theme editor rather than trusting any blog post about it, including this one.
The order, on one screen
| # | Check | Time | Tells you |
|---|---|---|---|
| 1 | Count variant rows in the admin | 30s | Whether the variant was ever created |
| 2 | Set one missing variant to continue selling, reload | 1m | Whether the theme is hiding sold-out combinations |
| 3 | Product status plus the Sales channels box | 1m | Whether the whole product is unpublished, draft or archived |
| 4 | Press End in each option value field | 2m | Invisible characters splitting one value into two |
| 5 | Count options on the product | 1m | Whether you ran out of room at three |
| 6 | Count variants; is it near 250? | 1m | The unpaginated Liquid ceiling |
| 7 | Compare channels | 5m | Variant level publication, owned by an app |
Steps 2 and 4 between them account for most of what we see. If you get to step 6 and the count really is around 250, you have learned something genuinely rare and you should probably restructure the product rather than paginate around it.
If the missing variants belong to colours you keep as separate products, that is a different shape of problem and a different app: linking them is what Rubik Combined Listings does with out of stock and archived products, at 5.0 stars across 65 reviews with a free plan for 5 groups. For the swatch side on a single product, our guide to hiding sold-out variant swatches goes further than this post does. You can also poke at the behaviour in the live demo store or read the docs FAQ before installing anything.
Frequently asked questions
Why do only some of my Shopify variants show on the product page?
Most often the theme is hiding combinations that are out of stock, using the availability flags Shopify exposes in Liquid. Shopify does not prescribe what a theme should do with an unavailable combination, so the behaviour and the setting name differ per theme. Check the variant picker block in your theme editor first.
How many options can a Shopify product have?
Three. Shopify’s documentation states “Each product can have up to three options. The options can be different from product to product.” The Admin API returns an OPTIONS_OVER_LIMIT error reading “Can only specify a maximum of 3 options” if you try for a fourth. The variant ceiling is separate: up to 2,048 variants per product.
Can a Shopify theme only show 250 variants?
Liquid’s product.variants is documented as returning a maximum of 250 variants when unpaginated, with the paginate tag as the documented workaround at up to 50 per page. Since Shopify allows up to 2,048 variants per product, a very large product can outrun what an unpaginated theme loop will render.
Does an archived product still show on the storefront?
No. Shopify defines ARCHIVED as “The product is no longer being sold and isn’t available to customers on sales channels and apps”, and DRAFT as “The product isn’t ready to sell and is unavailable to customers on sales channels and apps”. ACTIVE only means the product can be published, so also check the Sales channels box.
Why does the same colour appear twice in my variant picker?
Because the two values are not actually identical. Shopify rejects an exact duplicate with the error “Option value already exists”, so if both saved, something invisible differs: a trailing space, a non-breaking space from a spreadsheet, or a lookalike character from another alphabet. CSV imports are the usual source.
Which app should I use when variants show but the wrong images do?
Rubik Variant Images, if the variants belong to one product: it assigns a separate media set to each variant and controls whether sold-out swatches are hidden or disabled, at 5.0 stars across 420 reviews with a free plan. If your colours are separate products, Rubik Combined Listings links them into one listing with swatches instead. Neither app creates variants or edits product data, so fix the causes above first.
A variant is missing on one sales channel only. Why?
Shopify models publication at the variant level. The Admin API exposes publishedOnPublication, resourcePublications, unpublishedPublications and availablePublicationsCount on a product variant, so whichever app manages that channel’s catalog can exclude individual variants. Start with that app, not your theme.
Related reading
- How to hide unavailable variants on Shopify
- How to handle out of stock variants on Shopify
- Shopify 3 option type limit workarounds
- The Shopify 2,048 variant limit explained
- Choosing Shopify variant option names
- Hiding sold-out variant swatches on Shopify
Work the list in order. The variant is almost never gone, it is just being filtered by something that had no reason to tell you.
Umid
Co-Founder at Craftshift
