> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komerza.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Embed Not Loading

> Fix a Komerza checkout embed that doesn't open, shows an error, or never appears

If a buy button does nothing, the checkout modal never appears, or the embed shows an error instead of loading, this page walks through every common cause in the order worth checking.

<Card title="Check platform status first" icon="wave-pulse" href="https://status.komerza.com">
  If Komerza checkout is degraded, nothing below will help - status.komerza.com
  shows live availability for checkout and the API.
</Card>

## Are you a shopper, or the site owner?

<Tabs>
  <Tab title="I'm trying to buy something">
    You're on a store's website and checkout won't open. Try these, in order:

    1. **Reload the page.** A partly-loaded page is the most common cause.
    2. **Disable ad blockers and privacy extensions** for this site, then reload. Blockers frequently block checkout scripts.
    3. **Try a private/incognito window**, or a different browser.
    4. **Turn off any VPN or proxy** and retry.
    5. **Check [status.komerza.com](https://status.komerza.com)** in case checkout is down platform-wide.

    If none of that works, **contact the store you're buying from** - their support page or the contact details on their site. Komerza provides the checkout technology, but the store is run by an independent seller who handles their own orders, payments and refunds.
  </Tab>

  <Tab title="I own the site">
    Work through the checklist below. The fastest first move is the isolation
    test: open the [live demo
    page](https://checkout.komerza.com/embed/demo.html) in the same browser.

    * **The demo works, your site doesn't** → the problem is your page. Continue with the checklist.
    * **The demo also fails** → the problem is the browser, the network, or the platform. Check extensions, network restrictions and [status.komerza.com](https://status.komerza.com).
  </Tab>
</Tabs>

## Site owner checklist

<Steps>
  <Step title="Confirm the script actually loaded">
    Open your browser's developer tools → **Network** tab, reload, and look for
    `embed.iife.js`. It should return **200**.

    ```html theme={null}
    <script src="https://checkout.komerza.com/embed/embed.iife.js" defer></script>
    ```

    Then check the global exists - in the **Console**, run:

    ```javascript theme={null}
    typeof window.Komerza; // should be "object"
    ```

    If it returns `"undefined"`, the script didn't load, was blocked, or your
    code ran before it finished.
  </Step>

  <Step title="Call Komerza.init() after the DOM is ready">
    Data attributes are only bound when `init()` runs. If you use
    `data-kmrza-*` buttons, this is required:

    ```javascript theme={null}
    document.addEventListener("DOMContentLoaded", () => {
      Komerza.init();
    });
    ```

    With `Komerza.open()` this happens automatically, so a quick way to isolate
    a binding problem is to call `open()` directly from a click handler and see
    whether the modal appears.
  </Step>

  <Step title="Re-bind buttons rendered after init">
    Buttons added later - by a framework, a slider, infinite scroll, a
    single-page-app route change - were not present when `init()` ran, so they
    have no handler. Call `Komerza.init()` again after rendering, or drive those
    buttons with `Komerza.open()` instead.

    In React or Next.js, run `init()` inside `useEffect` so it fires after the
    component mounts, not during server rendering.
  </Step>

  <Step title="Verify the product and variant IDs">
    Both `productId` and `variantId` are required, both are UUIDs, and the
    variant must belong to that product **in the store the IDs came from**.
    Copying an ID from a different store is a common cause of a modal that opens
    and immediately errors.
  </Step>

  <Step title="Check the product is actually purchasable">
    The embed cannot check out a product your storefront wouldn't sell either. A
    product that is **Private**, **On Hold**, or out of stock will fail here
    too, as will a store with no payment method that fits the cart - see
    [Products & Variants](/guides/products-and-variants) and [Supported Payment
    Methods](/guides/payment-methods).
  </Step>

  <Step title="Rule out CSP and ad blockers">
    Both show up in the **Console** as blocked-resource errors. See the table
    below for which is which.
  </Step>
</Steps>

## Console errors and what they mean

| Error in the console                                                                    | Cause                                                                | Fix                                                                                      |
| --------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `Komerza is not defined`                                                                | The script hasn't loaded yet, or was blocked                         | Load the script before your code runs; keep `defer` and initialise on `DOMContentLoaded` |
| `KomerzaEmbed is not defined`                                                           | The global is `Komerza` - some older examples name it `KomerzaEmbed` | Use `Komerza.init()` and `Komerza.open()`                                                |
| `net::ERR_BLOCKED_BY_CLIENT`                                                            | An ad blocker or privacy extension blocked the request               | Test in a clean profile; ask affected shoppers to allowlist the site                     |
| `Refused to load the script … violates the following Content Security Policy directive` | Your CSP blocks the embed script                                     | Add `https://checkout.komerza.com` to `script-src`                                       |
| `Refused to frame 'https://checkout.komerza.com'`                                       | Your CSP blocks the checkout iframe                                  | Add `https://checkout.komerza.com` to `frame-src`                                        |
| `Refused to apply inline style`                                                         | Your CSP blocks the embed's styles                                   | Pass a nonce to `Komerza.init({ nonce })` and allow it in `style-src`                    |
| `Mixed Content: … requested an insecure resource`                                       | Your page is served over HTTP                                        | Serve the page over HTTPS                                                                |
| A 404 on `embed.iife.js`                                                                | Wrong script URL                                                     | Use `https://checkout.komerza.com/embed/embed.iife.js` exactly                           |

A working CSP for the embed looks like this:

```http theme={null}
Content-Security-Policy:
  frame-src https://checkout.komerza.com;
  script-src 'self' 'nonce-YOUR_NONCE' https://checkout.komerza.com;
  style-src 'self' 'nonce-YOUR_NONCE';
```

## The modal opens but looks wrong

<AccordionGroup>
  <Accordion title="It appears behind other elements">
    The modal uses a z-index of 9999. Something on your page is stacking above
    it - usually a sticky header, a cookie banner or a chat widget with a higher
    z-index. Lower theirs rather than raising the modal's.
  </Accordion>

  <Accordion title="It's clipped or cut off">
    An ancestor with `overflow: hidden`, a CSS `transform`, or a `filter`
    creates a new containing block that traps fixed-position content. Move the
    buy button out of that container, or remove the property.
  </Accordion>

  <Accordion title="The theme is wrong">
    `theme` accepts only `light`, `dark` or `auto`. Any other value - including
    a typo or an empty string - falls back to the default.
  </Accordion>

  <Accordion title="It flickers or opens twice">
    `init()` ran more than once and bound the same button twice. In frameworks,
    make sure your effect isn't re-running on every render.
  </Accordion>
</AccordionGroup>

## Still stuck?

Contact support with the following - it's the difference between a same-day fix and a week of back-and-forth:

* The **page URL** where the embed fails
* Your **store ID**, and the **product and variant IDs** you're passing
* **Browser and OS**, and whether it fails in a private window
* The **exact console errors**, copied as text
* Whether the [demo page](https://checkout.komerza.com/embed/demo.html) works in the same browser

<Note>
  If you're a customer of a store rather than its owner, contact that store's
  own support - Komerza runs the checkout technology but doesn't handle
  individual sellers' orders or refunds.
</Note>

## Related

<CardGroup cols={2}>
  <Card title="Embed SDK" icon="laptop-binary" href="/guides/embed-sdk">
    Full setup, API reference and framework examples.
  </Card>

  <Card title="System Status" icon="wave-pulse" href="https://status.komerza.com">
    Live availability for checkout and the API.
  </Card>

  <Card title="Supported Payment Methods" icon="credit-card" href="/guides/payment-methods">
    A cart with no available method can't check out.
  </Card>

  <Card title="Live Demo" icon="flask" href="https://checkout.komerza.com/embed/demo.html">
    A known-good embed to test your browser against.
  </Card>
</CardGroup>