Troubleshooting

OAuth & Authentication

"OAuth callback returned an error"

This usually means your app's callback URL is not configured correctly in the Partners Dashboard.

Make sure your redirect URL is set to:

https://your-app-url.com/_shopify/auth/callback

If you've changed authPathPrefix, adjust the URL accordingly.

"Session not found" or authentication keeps restarting

This happens when:

• You're using the default MemorySessionStorage and your server restarted (memory is cleared)
• The session storage adapter is not persisting data correctly

For production, switch to a persistent session storage adapter like Prisma, Drizzle, or Redis. See Configuration.

Token exchange fails in development

Make sure your appUrl matches the tunnel URL provided by shopify app dev. If the URLs don't match, Shopify will reject the token exchange.

App Bridge

"shopify is not defined" or App Bridge not loading

This means your app is not running inside the Shopify Admin iframe. Common causes:

• Opening the app URL directly in a browser instead of through the Shopify Admin
• The apiKey in your config doesn't match your Partners Dashboard app

useAppBridge() throws on server side

useAppBridge() is safe to call anywhere, but accessing properties (e.g., shopify.idToken()) will throw on the server. Move App Bridge calls into onMounted() or use <ClientOnly>.

Development Server

Vite host errors with Cloudflare tunnels

The module automatically sets vite.server.allowedHosts = true to allow Shopify's Cloudflare tunnel subdomains. If you still see host errors, ensure you're using the latest version of shopify-app-nuxt.

"Module not found" errors after config changes

Run bun run dev:prepare to regenerate type stubs and module setup after changing module options, routes, or auto-imports:

bun run dev:prepare

Webhooks

Webhook HMAC validation fails

Make sure:

• Your apiSecretKey is correct
• You're reading the raw body (not parsed JSON) — useShopifyWebhook() handles this automatically
• You're not using any middleware that consumes the request body before useShopifyWebhook()

Webhooks not being received

• Check that your webhook endpoint URL is reachable from the internet
• Verify webhooks are registered in your shopify.app.toml or via registerShopifyWebhooks()
• Check the Webhooks section in the Partners Dashboard for delivery failures

Polaris Components

Custom elements not rendering

If <s-button> or other Polaris web components aren't rendering, make sure:

• You're using the Sh* Vue wrapper components (e.g., <ShButton>) instead of raw s-* tags
• The Polaris CDN script is loading (check the browser console for network errors)

TypeScript errors with slot attributes

The module registers slot as a valid HTML attribute via type augmentation. If you see TypeScript errors related to slot, make sure your types are generated:

bun run dev:prepare