# Troubleshooting

Common setup issues and how to resolve them.

## SDK Script Not Loading

**Symptoms:** 404/CORS in Network tab, `window.LiquidCommerce.elements` is undefined.

**Fixes:**
- Verify the script URL and that the tag includes `data-liquid-commerce-elements`.
- Check ad blockers; proxy the API if needed.
- Confirm `data-env` is set correctly.

## Web Components Error

**Symptoms:** Console logs about Custom Elements or Shadow DOM.

**Fix:** Add the Web Components polyfill before the SDK:

```html
<script src="https://cdn.jsdelivr.net/npm/@webcomponents/webcomponentsjs@2/webcomponents-bundle.js"></script>
<script defer data-liquid-commerce-elements ...></script>
```

## Product Not Showing

**Symptoms:** Empty container or error view.

**Fixes:**
- Confirm the container ID matches your HTML.
- Verify the product identifier exists.
- Check for errors in the console or network tab.

## Cart Drawer Not Opening

**Symptoms:** Add to cart works but cart stays closed.

**Fixes:**
- Ensure a cart button is configured or call `window.LiquidCommerce.elements.actions.cart.openCart()`.
- Check for JavaScript errors in the console.

## Checkout Issues

**Symptoms:** Checkout fails to load or submit.

**Fixes:**
- Verify you are on a supported browser.
- Look for `checkout_*_failed` events in the console.
- Check for Stripe-related errors in the browser console.

## Address/Availability Problems

**Symptoms:** Products show unavailable or address prompts fail.

**Fixes:**
- Make sure the address is set and valid.
- Listen for `lce:actions.address_failed` to surface errors.

## SSR / Server-Side Rendering

**Symptoms:** Console warning "This SDK is designed for the browser. Calls made during SSR return null."

This is expected behavior. The SDK ships SSR stubs that are automatically resolved when bundled for Node.js (via the `node` export condition in `package.json`). There are two: the main build's stub (the `.` export) provides `Elements` and `ElementsBuilder` and warns with the `[LiquidCommerce Elements]` prefix; the checkout build's stub (the `./checkout` export) provides `ElementsCheckout` and warns with the `[LiquidCommerce Checkout]` prefix. Both re-export their types and enums for TypeScript compatibility and return `null` from the factory functions.

**No action required** — initialize the SDK in a client-only lifecycle hook (`useEffect`, `onMounted`, etc.) and the real client will activate in the browser.

## Styling Not Applied / CSS Not Working

**Symptoms:** Components render but custom styles are ignored, or host page styles leak into components.

**Cause:** Components use Shadow DOM for style isolation.

**Fixes:**
- Use `customTheme` in the client configuration to style components -- external CSS cannot penetrate Shadow DOM.
- For debugging, enable `development.openShadowDom: true` to make the shadow root open (`mode: 'open'`) so you can inspect component internals in DevTools (via `element.shadowRoot`). This does **not** disable style isolation — external CSS still cannot reach the components; use `customTheme` to style them. (Forced off in production.)
- Use the debug panel (`debugMode: 'panel'`) to inspect SDK logs, events, and GTM activity in real time — it surfaces a live stream of logger output and pubsub/GTM events (not component internal state), and auto-enables only in non-production environments.

## Component Not Updating After Data Changes

**Symptoms:** Component shows stale data after an action completes.

**Fixes:**
- Call `.rerender()` on the injected component to force a refresh:
  ```javascript
  const components = client.getInjectedComponents();
  components.get('product-1')?.rerender();
  ```
- Ensure you're not holding a stale reference -- call `getInjectedComponents()` again after injection.

## Cleanup / Memory Leaks

**Symptoms:** Components persist after navigating away in SPA, or duplicate components appear.

**Fixes:**
- Call `destroy()` on individual injected components when removing them:
  ```javascript
  const component = client.getInjectedComponents().get('product-1');
  component?.destroy();
  ```
- Call `client.destroy()` when tearing down the entire SDK (e.g., on SPA route change).

## Promo Ticker Not Showing

**Symptoms:** Promo ticker is configured but not visible.

**Fixes:**
- Verify all 5 required fields are set: `promoCode`, `text`, `separator`, `activeFrom`, `activeUntil`.
- Check that the current time falls between `activeFrom` and `activeUntil` (ISO 8601 UTC format).
- Ensure `global.layout.allowPromoCodes` is not set to `false`.

## Ad Blockers Blocking SDK Requests

**Symptoms:** Network requests fail, products don't load, but no code errors.

**Fixes:**
- Set up a proxy to route API requests through your own domain:
  ```javascript
  proxy: { baseUrl: 'https://yoursite.com/api/elements-proxy' }
  ```
- See [Proxy Setup Guide](../integration/proxy-setup.md) for server-side implementation.

## Performance Issues on Large Product Lists

**Symptoms:** Slow rendering or high memory usage with many products.

**Fixes:**
- Reduce `rows` and `columns` to load fewer products per page.
- Limit the number of active filters.
- Use the checkout-only build on checkout pages to reduce bundle size.

## Related Docs

- [Installation](../getting-started/installation.md)
- [Browser Support](./browser-support.md)
- [Error Handling](./error-handling.md)
- [Proxy Setup](../integration/proxy-setup.md)