# Troubleshooting

> Common issues and solutions for Lexsis Storefront pages

Canonical URL: https://fa7e86e3d553: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

After publishing, use the preview URL with a version parameter to bypass cache:

```
https://storefront.trylexsis.com/my-page?v=2
```

Increment the version number to see fresh content immediately.

## 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`