---
title: Troubleshooting
description: Solutions to common setup and runtime issues.
type: troubleshooting
---

# Troubleshooting



## Products not showing up

The most common cause is missing Storefront API permissions. In your Shopify admin, go to **Settings → Apps and sales channels → Headless → your storefront** and compare your token scopes against [Storefront API Permissions](/docs/reference/storefront-api-permissions).

Also check that your products are set to the **Online Store** and **Headless** sales channels in Shopify admin.

## Bundles not appearing (404 on the storefront)

A bundle that is **ACTIVE** in Shopify admin but 404s on the storefront is almost always missing from your **Headless** sales channel. The free Shopify Bundles app publishes a new bundle to the **Online Store** channel only, while the template's Storefront token reads from Headless — so `getProduct()` returns nothing and the route renders `notFound()`.

Fix it in admin: open the bundle product → **Publishing** → add your Headless channel. Then, because product reads are cached with `cacheLife("max")`, redeploy (or fire a product webhook) so the cached "not found" clears. The bundle's component products must be on Headless too, or their relationships won't resolve.

## Cart not persisting across page loads

The cart ID is stored in a `shopify_cartId` HTTP-only cookie with a 7-day expiry. Common causes:

* **Cookie domain mismatch** - if you're running on a different domain than expected, the cookie may not be sent. Check your browser dev tools → Application → Cookies.
* **Missing `invalidateCartCache()`** - every cart mutation must call `invalidateCartCache()` from `@/lib/cart/server`. Without it, the cached cart data goes stale and the UI may show an outdated state.

## Variant selection not working

Variant selection uses one option param per axis (`?color=Blue&size=XS`). If option links change the URL but the price/buy buttons do not update, check that `app/products/[handle]/page.tsx` parses the params with `parseSelectedOptions()` and resolves the variant with `getProductVariant()` inside the streamed `selectionPromise`.

Also confirm option links are generated with `buildOptionUrl()` from `lib/product.ts` (a pure merge of the current selection with the changed option), and that swatch availability comes from `getAvailableOptionValues()` in `lib/shopify/encoded-variants.ts` — if every value shows as available, the product's `encodedVariantAvailability` may be missing from the query.

## Images not loading

Shopify serves images from its CDN. The template's `next.config.ts` must include Shopify's image domain in `images.remotePatterns`. Verify that `cdn.shopify.com` is listed:

```ts
images: {
  remotePatterns: [
    { hostname: "cdn.shopify.com" },
  ],
},
```

## Build fails with GraphQL errors

This usually means the query references a field, argument, or enum value that doesn't exist on the live Shopify API version your store is using.

Re-check and validate the operation with Shopify AI Toolkit first. Then use the [`shopify-graphql-reference` skill](/docs/skills/shopify-graphql-reference) for the template integration and cache role.

If the Shopify plugin is missing, reinstall it:

```bash
npx plugins add Shopify/shopify-ai-toolkit --scope project --yes
```

## Changes in Shopify not appearing on the site

All product and collection data is cached with `cacheLife("max")`. Without webhooks configured, changes only appear when the cache expires.

To get near-instant updates, set up Shopify webhooks pointed at `/api/webhooks/shopify`. See [Webhooks](/docs/anatomy/webhooks) for the full setup guide.

## Locale or currency not changing

Multi-locale commerce requires Shopify Markets to be enabled. The template ships as single-locale by default. Run [`/vercel-shop:enable-shopify-markets`](/docs/skills/enable-shopify-markets) to add regional locale routing and propagate Shopify's localized country, language, and currency context. The skill supports locale-prefixed, invisible cookie-based, and per-domain routing.

## Agent can't find context files

Coding agents rely on `AGENTS.md` in the project root plus the expected project-scoped plugins. If an agent is missing context or commands:

* Verify you cloned from the correct template (`vercel/shop`, `apps/template` path)
* The `AGENTS.md` file should be at the project root, not nested in a subdirectory
* Check that `.claude/settings.json` exists and that the project plugins are enabled
* Rerun the project plugin setup from the project root if needed:

```bash
npx create-vercel-shop@latest --no-template
```

If that still fails, rerun the plugin installs individually:

```bash
npx plugins add vercel/shop --scope project --yes
npx plugins add vercel/vercel-plugin --scope project --yes
npx plugins add Shopify/shopify-ai-toolkit --scope project --yes
```


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)