# Troubleshooting

> Common issues and solutions for Lexsis Storefront pages

Canonical URL: https://c22dfdd27662:3005/troubleshooting

This section covers common problems you may encounter when building and publishing Storefront pages, along with their solutions.

## Available Guides

- [Islands Not Working](/troubleshooting/islands-not-working) — Island hydration and rendering failures
- [Product Resolution Issues](/troubleshooting/product-resolution) — Product data problems in island components
- [Publish Errors](/troubleshooting/publish-errors) — Publishing and validation failures
- [Styling Issues](/troubleshooting/styling-issues) — CSS and styling problems

## General Debugging Tips

### Check the Browser Console

Most island and rendering issues show detailed error messages in the browser console. Open DevTools (F12) and check the Console tab for errors.

### Validate Before Publishing

Always call `lexsis_pages` with action `compile` before
`lexsis_page_create` with action `create`:

```typescript
const validation = callTool("lexsis_pages", {
  action: "compile",
  args: { source, head },
});
if (!validation.ok) {
  console.log(validation.compile_issues, validation.validation_errors);
}
```

### Test Islands Individually

If multiple islands aren't working, comment them out one by one to isolate the problematic island.

### Use the Preview URL

Use the `preview_url` returned by MCP to inspect a draft. Use the returned
published URL to verify live behavior, and compare its published version with
the version you reviewed. Do not invent a route or cache-busting version
parameter.

## Quiz troubleshooting

| Symptom | What to check |
|---|---|
| No result products | Refresh the selected store's catalog. Verify Product GIDs, result product keys, availability, and required variant options. |
| Preview works, no saved response | Preview does not collect production responses. Verify the published version, active capture policy, and shopper's saving consent. |
| Policy conflict after editing | Inspect the new immutable page-version UUID and definition hash, prepare its policy, and activate with the current active-definition ID. |
| Result shown, save failed | Completion and persistence differ. Read the save status and retry an unconfirmed save; do not claim success from the result screen alone. |
| Forms response, no quiz analytics | Check analytics consent and page-view linkage. Saving while analytics is denied is supported. |
| Responses missing from a list | Check workspace/store, definition, status, test-mode filters, pagination, and retention. Normal tests on a published page are not automatically test data. |
| Contact answers hidden in MCP | MCP details redact personal/sensitive fields. Use the merchant response viewer's authorized reveal controls. |
| Reload cannot restore | Check the resume window, retention, active policy, and currently published version. Historical-version resume is not supported. |
| Unexpected gift, coupon, or cart total | Inspect the effective Cart V2 profile and Shopify outcomes. Quiz result selection does not prove a promotion applied. |
| Transition loses focus or feels excessive | Check keyboard focus, back/review navigation, and reduced-motion behavior at mobile and desktop widths. |

See [Forms and Quiz Responses](/tools/forms) and the
[Quiz contract](/islands/engagement/quiz).

## Common Mistakes

1. **Using product handle instead of GID** — Always use `gid://shopify/Product/123` format
2. **Malformed island JSON** — The JSON script child must contain one valid object
3. **Multiple BuyBox/CartDrawer instances** — Only one of each per page
4. **Nested islands** — Islands cannot be nested; keep them side-by-side
5. **Missing listenForEvents** — Islands that need to react to events must have `listenForEvents: true`