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.

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

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 relies on a rewrite rule in next.config.ts that maps ?variantId=123 to a route segment:

rewrites: async () => [
  {
    source: "/products/:handle",
    has: [{ type: "query", key: "variantId", value: "(?<variantId>.+)" }],
    destination: "/products/:handle/:variantId",
  },
],

If this rule is missing or modified, clicking a variant option will append a query parameter but the page won't re-render with the new variant.

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:

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 the operation with shopify-ai-toolkit or the shopify-graphql-reference skill and confirm each field against the live schema before changing the query.

If the Shopify plugin is missing, reinstall it:

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 Shopify Integration → Webhooks for the full setup guide.

Locale or currency not changing

Multi-locale support requires Shopify Markets to be enabled. The template ships as single-locale by default. Run /vercel-shop:enable-shopify-markets to add multi-locale and multi-currency 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:

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

If that still fails, rerun the plugin installs individually:

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