Troubleshooting
Fix the most common Joy Loyalty issues on Weaverse storefronts — empty blocks, Studio and CSP problems, token errors and caching.
Weaverse Studio and the Joy block
| What you see | Cause | Fix |
|---|---|---|
| The block shows "Set the JOY_API_URL and JOY_SHOP_DOMAIN..." | The block loader can't read the Joy variables from weaverse.env. | Add the variables to .env and to each Oxygen environment, and pass them through to Weaverse. |
| The block is empty | The store is on Loyalty Page V1, or the Joy variables are missing. | Switch to Loyalty Page V2 in Joy admin and check the environment variables. |
| Old Joy blocks disappeared after updating | Version 0.2.0 replaced them with the Loyalty Page block. | Add the Joy — Loyalty Page block and pick the section you need. See Loyalty Page block. |
| Studio preview breaks, or Joy is blocked only in Studio | Your Weaverse CSP and the Joy CSP weren't merged. | Start from getWeaverseCsp and add each Joy list to it. See Install manually. |
| Studio shows stale content, or a preview is served to shoppers | Weaverse preview requests are being page-cached. | Exclude requests with weaverseHost, isDesignMode, __revisionId and similar parameters from full-page caching. |
| Two launchers on the page | Both <JoyWidget/> and the Joy — Loyalty Launcher block are used. | Keep one. |
| Redeeming in the block doesn't update your cart or drawer | The block can't reach your cart. | Wrap your page content in <JoyProvider cart onCartUpdated onOpenCartDrawer>. |
Sign-in and tokens
| What you see | Cause | Fix |
|---|---|---|
/api/joy-token returns 500 missing_env | A Joy environment variable is missing. | Add JOY_API_URL, JOY_SHOP_DOMAIN and JOY_API_SECRET to .env and to each Oxygen environment (Preview and Production are separate). |
Logged-in customers get 401 exchange_failed, or the token request repeats | JOY_API_SECRET is wrong, was revoked, or is the REST Secret key instead of the Headless secret — or JOY_SHOP_DOMAIN isn't your myshopify domain. | Copy the current secret from Joy admin > Settings > Manage keys > Headless secret, and use your-store.myshopify.com. |
Logged-in customers get 401 customer_unresolved | The customer's ID or email couldn't be read from the Customer Account API. | Check your Customer Account API login setup. |
/api/joy-token returns 502 exchange_failed; Joy API requests return 403 with PLAN_NOT_ELIGIBLE | Your store isn't on the Ultimate plan. | Upgrade to the Ultimate plan in Joy admin. |
One customer gets 502 exchange_failed while others work | The customer is excluded from your loyalty program. | Expected. Remove the exclusion in Joy admin if this is a mistake. |
/api/joy-token returns 502 upstream_unreachable | JOY_API_URL is wrong or unreachable. | Use https://api.joy.so/app/api/v1/headless, including the path. |
| Logged-in customer sees the guest widget | A cached guest page was served. | Don't page-cache requests with a customer session cookie or personalized Joy data. |
Widget and display
| What you see | Cause | Fix |
|---|---|---|
| Widget stuck on a loading skeleton, or "[joy] failed to load the widget core" in the console | The widget code is blocked by script-src, or you are on @joy-loyalty/hydrogen 0.2.0 without JOY_WIDGET_ASSET_URL. | Merge the Joy CSP lists. Upgrade to @joy-loyalty/hydrogen 0.2.1 or later — or, on 0.2.0, set JOY_WIDGET_ASSET_URL=https://api.joy.so. |
Images or icons missing; CSP errors for img-src or font-src | Only some Joy CSP lists were merged. | Merge all five Joy lists and keep cdn.shopify.com in imgSrc. |
| Redeemed coupon shows a code but isn't applied | Cart wiring is incomplete. | Pass both cartFetcher and cartRevalidate to <JoyWidget/>, and a locale-aware cartRoute. |
| Joy texts in the wrong language | locale isn't passed, or isn't lowercase. | Pass storefront.i18n.language.toLowerCase(). |
Build error: cannot resolve dompurify | Your package manager doesn't hoist dependencies (pnpm, Yarn PnP). | Run npm i dompurify. |
Using an AI coding agent? Ask it: "Use the joy-headless-install skill to diagnose my Joy Loyalty integration on Weaverse. Symptom: <what you see>." See Install with an AI agent.
Still stuck?
Contact us through the in-app chat with your storefront URL, the symptom, and a screenshot of the browser console and network tab — we are happy to help.