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

# SDK troubleshooting

> Web SDK code-level issues — Webpack polyfills, singleton initialization, codec ID resolution, reconnection state, and allowed-origin validation.

This page covers Web SDK **code-level** issues — problems you hit while wiring the SDK into your app. Click any item below to expand it.

<Info>
  For blurry streams, connection failures, audio problems, mobile disconnects, or stuck builds, see the general [Troubleshooting](/resources/concepts/troubleshooting) page first. Those issues apply to all Streampixel users, not just SDK developers.
</Info>

## Build & setup

<AccordionGroup>
  <Accordion title="Webpack polyfill errors" icon="cube">
    **Symptom:** Build errors like `Module not found: Error: Can't resolve 'crypto'` or similar.

    The SDK requires Node.js polyfills for browser use. See the [Installation](/resources/web-sdk/getting-started/installation) page for the complete `config-overrides.js` setup.
  </Accordion>

  <Accordion title="Stream works locally but not in production" icon="globe">
    **Symptom:** Everything works on `localhost` but fails when deployed.

    **Solutions:**

    * The SDK validates `window.location.origin` against the project's allowed URLs list in the dashboard. Add your production domain to the `validPathUrl` setting.
    * `localhost` is always allowed for development.
    * Wildcard patterns are supported (e.g., `*.example.com`).
  </Accordion>
</AccordionGroup>

## Runtime & integration

<AccordionGroup>
  <Accordion title="&#x22;StreamPixelApplication called more than once&#x22;" icon="rotate">
    **Symptom:** Console warning and SDK returns empty object `{}`.

    `StreamPixelApplication` is a singleton — it can only be initialized once per page. This commonly happens in React when:

    * The component re-renders and calls `StreamPixelApplication` again
    * `useEffect` dependencies change, triggering reinitialization

    Fix: Use a ref or flag to ensure single initialization:

    ```javascript theme={"dark"}
    const initialized = useRef(false);

    useEffect(() => {
      if (initialized.current) return;
      initialized.current = true;

      StreamPixelApplication({ appId }).then(/* ... */);
    }, [appId]);
    ```
  </Accordion>

  <Accordion title="Default Pixel Streaming UI showing through" icon="eye-slash">
    **Symptom:** You see unfamiliar buttons, panels, or overlays from the default PS UI.

    **Solutions:**

    * Add CSS to hide the default UI:
      ```css theme={"dark"}
      #uiFeatures { display: none !important; }
      #afkOverlay { display: none !important; }
      ```
    * Also hide programmatically after initialization:
      ```javascript theme={"dark"}
      const uiEl = appStream.rootElement?.querySelector('#uiFeatures');
      if (uiEl) uiEl.style.display = 'none';
      ```
    * The `#uiFeatures` element may re-appear after `onVideoInitialized`, so hide it in that callback too.
  </Accordion>

  <Accordion title="Video codec shows raw ID instead of name" icon="film">
    **Symptom:** Stats show something like `RTCCodec_1_Inbound_120` instead of `H264`.

    Resolve the codec ID from the codecs Map:

    ```javascript theme={"dark"}
    pixelStreaming.addEventListener('statsReceived', (e) => {
      const stats = e.data.aggregatedStats;
      const codecId = stats.inboundVideoStats.codecId;
      const codec = stats.codecs.get(codecId);
      console.log('Codec:', codec?.mimeType); // "video/H264"
    });
    ```
  </Accordion>

  <Accordion title="Reconnection not working" icon="arrows-rotate">
    **Symptom:** After a disconnect, the SDK doesn't attempt to reconnect.

    **Solutions:**

    * Automatic reconnection only triggers for WebSocket close codes **1005** and **1006** (abnormal closures). All other codes (project inactive, max runtime, etc.) are intentional disconnects.
    * The reconnection window is **60 seconds**. If the server doesn't respond within that time, reconnection fails with code 4007.
    * Listen to `reconnectStream.on('state', ...)` to see the exact state transitions and codes.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="General troubleshooting" icon="wrench" href="/resources/concepts/troubleshooting">
    Stream quality, connection, audio, and build issues that apply to all users.
  </Card>

  <Card title="reconnectStream API" icon="rotate" href="/resources/web-sdk/api-reference/reconnectstream">
    Inspect reconnection state and disconnect codes.
  </Card>

  <Card title="Stream statistics" icon="chart-line" href="/resources/web-sdk/features/stream-statistics">
    Use stats to diagnose codec, bitrate, and packet loss issues.
  </Card>
</CardGroup>