---
title: Troubleshooting
description: Solutions to common setup and runtime issues.
url: "https://shop-docs.labs.vercel.dev/docs/reference/troubleshooting"
docs_index: /llms.txt
lastUpdated: 2026-10-13
type: troubleshooting
---

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

## 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 active and published to the **Headless** sales channel.

**Fix:** Grant the missing scopes and publish the products to Headless. Publishing to **Online Store** alone is not enough.

**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 the bundle and its component products to Headless. If the route still returns `404`, confirm that a product webhook for the bundle reaches the storefront to invalidate the cached 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 cart survives navigation and reloads on the same domain. The cookie has a 14-day lifetime, but it does not guarantee that Shopify will retain the cart or that the browser will keep the cookie.

## 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 and values are matched case-insensitively. 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", protocol: "https" }],
},
```

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

## A Storefront request fails with GraphQL errors

**Symptom:** `assertStorefrontOk()` throws, or the response 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; typecheck does not catch invalid fields.

**Fix:** Correct the operation and load the affected route again.

If Shopify AI Toolkit is unavailable, install it for your agent with [Shopify's install instructions](https://github.com/Shopify/shopify-ai-toolkit#install).

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

**Expected result:** The route renders and the Storefront response carries no `errors`.

## 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`. The endpoint returns `404` when `SHOPIFY_WEBHOOK_SECRET` is not set and `401` when a signature does not match.

**Fix:** Point the required Shopify webhooks to `POST /api/webhooks/shopify`. Follow [Webhooks](/docs/anatomy/webhooks) for setup. After a product or collection edit, check that Shopify reports a successful delivery and that the endpoint returns a nonempty `tagsInvalidated` list.

**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:** The default serves one deployment using `shopConfig.localization` in `lib/config/index.ts`. Storefront copy, display formatting, and Shopify commerce context are separate. A formatting locale does not translate labels or convert prices.

**Fix:** Edit [storefront copy](/docs/anatomy/i18n) for a single-language deployment, or use [Enable i18n](/docs/skills/enable-i18n) for translated UI and locale URLs. For regional commerce, run the [`enable-shopify-markets` skill](/docs/skills/enable-shopify-markets) and choose locale-prefixed, cookie-based, or per-domain routing.

**Expected result:** Copy changes affect labels. Markets changes send the selected commerce context to Shopify; currency comes from Shopify's response, not a storefront currency map.

## A coding agent cannot find project context

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

**Check:** Confirm the project root has `AGENTS.md` and the Shop skills in `.agents/skills/`. Claude Code reads the skills through the `.claude/skills` link. Skill support depends on the agent.

**Fix:** From the project root, add the Shop skills:

```bash
pnpm dlx skills add vercel/shop --skill '*' --yes
```

This command adds skills; it does not restore a missing `AGENTS.md`. Restore that file from your project's version control if it was removed. To install the Vercel plugin and Shopify AI Toolkit, see [Extending with Agents](/docs/getting-started/extending-with-agents#set-up-the-agent).

**Expected result:** Your agent lists the Shop skills and can read the project guidance.

---

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)