Most publishes finish in seconds. When something goes wrong, this guide covers the common problems and how to resolve them.
Publish button is disabled
Cause: The project has no layouts — the Publish button is disabled on an empty project.
Fix: Create a layout in the Layouts & layers panel, select it, then click Publish.
An upgrade prompt appears
Cause: Your plan doesn't allow publishing this layout type, or you've reached a publish limit for it.
Fix: Some layout types and features require a paid plan:
Feature | Plan |
Publish your home page | Starter and up |
Publish a cart drawer | Pro and up |
Publish to a draft theme | Pro and up |
Shopify Markets across all layout types | Business |
Product and collection templates and custom headers and footers also require a paid plan. Your plan's exact limits are shown in Settings → Plans. Upgrade there, or unpublish an existing layout of the same type to free a slot within your current limit.
Instant Embed not enabled
Cause: Instant Embed isn't active on your target theme, so Instant prompts you during publish.
Fix:
In the prompt, click Enable in Shopify.
In the Shopify theme editor, turn on Instant Embed under App embeds (Shopify's own label).
Click Save in the Shopify editor.
Return to Instant and click Verify & Publish.
You can instead choose Skip & Publish. Your layouts still work — Instant Embed just makes them load faster.
Links don't work on the published page
Cause: Almost always a Link to action with no destination set. The element still publishes, but the link points nowhere, so clicking it does nothing.
Fix:
Select the element and open the Interactions tab in the Design panel.
In the Action section, check the Link to action actually has a destination — a URL, or a Shopify page, product, collection, blog article, or policy page.
Check any elements you duplicated or copied between layouts. The action comes along with the copy, but the destination may be empty or point somewhere that no longer fits.
Republish and test the link on your storefront.
If the element has no action at all, it isn't a link yet — see Add interactions and conditional visibility. If a parent container has its own action, that can override the one on your button; Instant flags this with an Overlap in Actions warning.
Publish succeeds but the page isn't visible
Possible causes and fixes:
Wrong theme — Check the target theme in Settings → Shopify. If you published to a draft theme, the layout isn't on your live storefront. Switch to the live theme and republish, or use Shopify's theme preview.
Store is password-protected — The public sees Shopify's password page. See Password-protected stores.
Handle changed — Confirm the URL in the layout's settings General tab under Handle.
Home page not set — If you expect the page at your root URL, confirm it's set as your home page and published.
Product or collection template not applied
Cause: No products or collections are assigned to the template.
Fix: Open the layout's settings General tab and assign the products or collections. Assignment takes effect without republishing.
Section not in the theme editor
Cause: The section wasn't published, or its Use in Shopify settings restrict where it can appear.
Fix:
Confirm the section shows as published.
In section settings, check Use in Shopify and enable Templates, Header, or Footer as needed.
Republish if you changed Use in Shopify.
Open the Shopify theme editor and add the section.
Cart drawer not appearing
Cause: The cart isn't published, or it isn't set as your main cart.
Fix:
Confirm you're on the Pro plan or higher (required to publish carts).
Publish the cart layout.
In the cart's settings, choose Set as main cart.
Turn on Instant cart actions in the cart's settings if add-to-cart buttons don't open the drawer.
Publish fails during deployment
You'll see Failed to upload files to Shopify, please contact support if the issue persists.
Cause: This is usually a theme issue. Instant needs an Online Store 2.0 theme (often called Shopify 2.0), and older themes can't accept the files Instant publishes.
Fix:
Check which theme you're publishing to in Settings → Shopify.
Ask your theme provider or developer to confirm that theme is fully Online Store 2.0 compliant. Current Shopify Theme Store themes are; themes carried over from older stores, and heavily customized ones, often aren't.
Wait a moment and publish again, in case Shopify was briefly unavailable.
Contact support with the layout type and the target theme for assistance.
It shows up most often when setting a page as your home page, setting a header, footer, or cart as your main one, or setting a default product or collection template.
Changes not appearing after republishing
Cause: Browser or Shopify caching, or content managed in Shopify overriding Instant.
Fix:
Hard-refresh the page (
Ctrl+Shift+R/Cmd+Shift+R) or check in an incognito window.Confirm you edited and published the correct layout — check the name in Layouts & layers.
If text or media is managed in Shopify, enable Overwrite content in Shopify in the publish menu's Advanced options, then confirm the Overwrite all Shopify content? dialog when you publish. See Manage content in Shopify.
Republish all layouts
If you switched themes or several layouts seem out of sync, go to Settings → Shopify → Published layouts → Republish all. This redeploys every published layout to the currently selected theme.
Still stuck?
Contact support with the layout type, target theme, the error message, and whether Instant Embed is enabled.