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

# Troubleshooting



## Products do not appear

**Symptom:** Product pages or listings are empty.

**Check:** In Shopify admin, confirm the Storefront token has the scopes in [Storefront API Permissions](/docs/reference/storefront-api-permissions). Confirm each product is published to both the **Online Store** and **Headless** sales channels.

**Fix:** Grant the missing scopes and publish the products to both channels.

**Expected result:** Published products appear in listings and product routes resolve.

## A bundle returns 404

**Symptom:** A bundle is active in Shopify admin but its storefront route returns `404`.

**Check:** Open the bundle product's **Publishing** settings. Confirm the bundle and its component products are published to the **Headless** sales channel.

**Fix:** Publish all required products to Headless. Then trigger a product webhook or redeploy to clear the cached not-found response.

**Expected result:** The bundle route loads and its component relationships appear.

## The cart does not persist

**Symptom:** The cart becomes empty after navigation or reload.

**Check:** In browser developer tools, open **Application → Cookies** and confirm the `cart` cookie exists for the current domain. It should have a 14-day expiry.

**Fix:** Use one consistent storefront domain and remove any deployment or proxy setting that rewrites the cookie domain.

**Expected result:** The same cart remains available across page loads for up to 14 days.

## Variant selection does not update the product

**Symptom:** Selecting an option changes the URL but not the price or purchase controls.

**Check:** Confirm the URL contains one query parameter per option, such as `?color=Blue&size=XS`. Option names are lowercase. Confirm the selected combination exists in Shopify.

**Fix:** Correct links to preserve all selected option parameters. If a valid combination still fails, validate the product and variant queries against the Storefront API schema.

**Expected result:** The URL, selected variant, price, availability, and purchase controls update together.

## Images do not load

**Symptom:** Shopify product images are broken or rejected by Next.js Image.

**Check:** Confirm `next.config.ts` allows `cdn.shopify.com` in `images.remotePatterns`.

**Fix:** Add the Shopify CDN hostname:

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

**Expected result:** Shopify CDN images render through Next.js Image.

## The build fails with GraphQL errors

**Symptom:** Codegen or the production build reports an invalid GraphQL field, argument, type, or enum value.

**Check:** Validate the operation against the live Storefront API schema for the configured `SHOPIFY_API_VERSION` using Shopify AI Toolkit.

**Fix:** Correct the operation, then run:

```bash
pnpm --filter template codegen
```

If Shopify AI Toolkit is unavailable, install the project plugin:

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

Use the [`shopify-graphql-reference` skill](/docs/skills/shopify-graphql-reference) only for template integration conventions.

**Expected result:** Codegen exits successfully and the production build passes its GraphQL validation gate.

## Shopify changes do not appear

**Symptom:** Updated products or collections still show old content.

**Check:** Confirm Shopify webhooks are configured and signed with `SHOPIFY_WEBHOOK_SECRET`.

**Fix:** Point the required Shopify webhooks to `POST /api/webhooks/shopify`. Follow [Webhooks](/docs/anatomy/webhooks) for setup. Redeploy once if you need to clear existing stale entries.

**Expected result:** Shopify changes invalidate the affected cached content and appear without a redeploy.

## Locale or currency does not change

**Symptom:** The storefront keeps one language or currency after a regional selection.

**Check:** Confirm Shopify Markets is enabled. The template is single-locale by default.

**Fix:** Run [`/vercel-shop:enable-shopify-markets`](/docs/skills/enable-shopify-markets) and choose locale-prefixed, cookie-based, or per-domain routing.

**Expected result:** Requests carry the selected country and language context, and Shopify returns localized content and currency.

## A coding agent cannot find project context

**Symptom:** A coding agent misses project commands or shop-specific guidance.

**Check:** Confirm the project root contains `AGENTS.md` and `.claude/settings.json`, and that the expected project plugins are enabled.

**Fix:** From the project root, run:

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

If needed, install the plugins 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
```

**Expected result:** The agent loads the project guidance and the Vercel Shop, Vercel, and Shopify tools.


---

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)