# Islands Not Working

> Common island hydration and rendering failures

Canonical URL: https://fa7e86e3d553:3005/troubleshooting/islands-not-working

Common island hydration and rendering failures.

For new pages and section edits, author islands with `<lx-island>` plus a JSON
script child, then run `lexsis_pages` with action `compile`.

## Symptom: Island Not Rendering

The island component doesn't appear on the page at all.

### Cause

The `<lx-island name>` value is misspelled, uses wrong case, or isn't in the
valid islands catalog.

### Fix

Use the exact case-sensitive island name from the catalog. Check available islands at `/docs/resources/island-catalog`.

```html
<!-- WRONG: wrong case -->
<lx-island name="buybox"></lx-island>

<!-- RIGHT: exact case-sensitive name -->
<lx-island name="BuyBox"></lx-island>
```

## Symptom: Props Parse Error

Island renders but console shows parsing error, or island shows default/broken state.

### Cause

The JSON script child is malformed, missing, or does not contain an object.

### Fix

Use one JSON script child under `<lx-island>`. Apostrophes and formatted JSON
are safe inside the script.

```html
<lx-island name="BuyBox">
  <script type="application/json">
{
  "product": {
    "title": "example-title",
    "price": "example-price",
    "variants": []
  }
}
  </script>
</lx-island>
```

## Symptom: Multiple purchase controls diverge

Page loads but cart functionality is broken or unpredictable.

### Cause

BuyBoxes or StickyBar instances intended to represent one purchase flow do not
share a `syncKey`, or separate products accidentally reuse the same key.

### Fix

Use a unique `syncKey` when multiple BuyBoxes intentionally represent the same
purchase group. Cart V2 is enabled by default and the renderer injects the
effective profile; never author CartDrawer or DrawerShell in page source.

```html
<lx-island name="BuyBox">
  <script type="application/json">
{
  "product": {
    "title": "example-title",
    "price": "example-price",
    "variants": []
  }
}
  </script>
</lx-island>
```

## Symptom: Compilation succeeds but the island is incomplete

### Cause

Compilation validated serialization, but registration, hydration, runtime
props, output, controls, or event timing failed in the browser.

### Fix

Inspect the rendered island:

- `data-lx-hydration-state="ready"` means initial runtime rendering completed.
- `data-lx-hydration-state="error"` and `data-lx-hydration-error` identify the
  failure class.
- Preview QA reports missing registration, invalid runtime props, empty output,
  missing required controls, island exceptions, and hydration-order event loss.

Do not treat a successful compile as proof that the island works.

## Symptom: Variant events affect another product

### Cause

Several product interaction groups share the page without separate
`data-scope` wrappers.

### Fix

Wrap each ProductGallery/ProductHero, selector, and BuyBox group in a unique
scope. Listening islands resolve the closest scope and ignore unrelated
events.

## Symptom: Purchase succeeds but no cart opens

### Cause

The page has purchase controls but no effective published Cart V2 profile.

### Fix

Resolve or assign a profile. Preview reports
`data-lx-cart-profile-state="missing"` and an `lx:preview-warning`. Cart V2 is
already enabled; adding a flag or inline DrawerShell does not fix a missing
profile.

## Symptom: Raw media warning

### Cause

New source authors a standalone image or video element where a native media
island should own responsive media, controls, loading, or motion.

### Fix

Use `HeroMedia`, `MediaCarousel`, `ProductGallery`, `ProductHero`, or
`VideoPlayer`. The compiler warning code is
`native_media_island_recommended`.

## Symptom: Nested Islands Don't Work

Inner island doesn't hydrate or causes console errors.

### Cause

Islands cannot be nested inside other islands. Each island is an isolated hydration boundary.

### Fix

Flatten the structure. Place islands side-by-side, never nested.

```html
<lx-island name="BuyBox">
  <script type="application/json">
{
  "product": {
    "title": "example-title",
    "price": "example-price",
    "variants": []
  }
}
  </script>
</lx-island>

<lx-island name="VariantSwatches">
  <script type="application/json">
{}
  </script>
</lx-island>
```

## Symptom: Island Shows But Doesn't React

Island renders but doesn't respond to events from other islands (e.g., BuyBox doesn't update when VariantSwatches changes).

### Cause

Listener island is missing `listenForEvents: true` prop.

### Fix

Add `listenForEvents: true` to the island that needs to react to `variant:changed` events.

```html
<lx-island name="VariantSwatches">
  <script type="application/json">
{}
  </script>
</lx-island>

<lx-island name="BuyBox">
  <script type="application/json">
{
  "product": {
    "title": "example-title",
    "price": "example-price",
    "variants": []
  }
}
  </script>
</lx-island>
```

## Symptom: OptionResolver Not Coordinating

BuyBox still shows its own variant selector even though OptionResolver exists.

### Cause

BuyBox renders its default variant selector unless explicitly disabled.

### Fix

Set `showVariantSelector: false` on BuyBox when using OptionResolver.

```html
<lx-island name="OptionResolver">
  <script type="application/json">
{
  "variants": [
    {
      "id": "example-id",
      "selectedOptions": "example-selectedOptions",
      "price": "example-price",
      "available": true
    }
  ],
  "options": [
    {
      "name": "example-name",
      "position": 0
    }
  ]
}
  </script>
</lx-island>

<lx-island name="BuyBox">
  <script type="application/json">
{
  "product": {
    "title": "example-title",
    "price": "example-price",
    "variants": []
  }
}
  </script>
</lx-island>
```

## Symptom: Missing JSON Script

Compilation reports that an island has no props object.

### Cause

The island is missing its `script[type="application/json"]` child.

### Fix

Add one JSON script child. The JSON may span multiple lines.

```html
<lx-island name="BuyBox">
  <script type="application/json">
{
  "product": {
    "title": "example-title",
    "price": "example-price",
    "variants": []
  }
}
  </script>
</lx-island>
```

## Symptom: Wrong Product Format Error

Console shows "Product not found" or "Invalid product ID".

### Cause

Using product handle (slug) or bare numeric ID instead of Shopify GID format.

### Fix

Always use full Shopify GID format: `gid://shopify/Product/123456789`

```html
<lx-island name="BuyBox">
  <script type="application/json">
{
  "product": {
    "title": "example-title",
    "price": "example-price",
    "variants": []
  }
}
  </script>
</lx-island>
```