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

# Mascotbot React SDK Troubleshooting

### Module Resolution Issues in Next.js Pages Router

If you encounter errors like:

```bash theme={null}
SyntaxError: Named export 'X' not found. The requested module '@rive-app/react-canvas' is a CommonJS module...
```

This occurs because Next.js Pages Router has stricter module resolution rules compared to App Router. To fix this:

1. Add `@mascotbot-sdk/react` to your `next.config.js`:

```js theme={null}
/** @type {import("next").NextConfig} */
const nextConfig = {
  transpilePackages: ["@mascotbot-sdk/react"]
}
module.exports = nextConfig
```

2. If you're still seeing issues, try clearing your Next.js cache:

```bash theme={null}
rm -rf .next
```

### `MascotCall` Common Issues

#### Transport State Stuck on "Connecting"

If the call state remains in "connecting":

* Check that your `apiUrl` is correct and accessible
* Ensure your browser has microphone permissions
* Check browser console for any WebRTC-related errors

#### Audio Issues

If you're experiencing audio problems:

1. Check microphone permissions in your browser
2. Verify that no other application is using the microphone
3. Try refreshing the page to reset WebRTC connections

#### Animation Not Playing

If the Rive animation isn't working:

1. Verify your Rive file URL is correct
2. Check that artboard and animation names match your Rive file

### Lip Sync Breaks Mid-Conversation (ElevenLabs)

If the mouth gets stuck or lip sync stops working during a conversation, the cause is almost always **parent re-renders destroying `MascotPlayback`**.

**What happens:** `useRiveInputs()` returns a new container object on every render. This is a dependency of the internal `useEffect` that creates `MascotPlayback`. Any state change that re-renders an ancestor of `MascotClient` — tool call side effects, polling, UI interactions — cascades through, recreating `MascotPlayback` and killing the active animation-frame loop mid-speech.

**Fix:** Ensure your `MascotClient` tree doesn't re-render when tool calls fire. Two approaches:

1. **Memoize the MascotClient subtree** — pass mutable data (items, callbacks) via a ref, and wrap the `<MascotProvider>` + `<MascotClient>` block in `useMemo(() => ..., [])`:

```tsx theme={null}
const propsRef = useRef(props);
propsRef.current = props;

const widget = useMemo(() => (
  <MascotProvider>
    <MascotClient ...>
      <VoiceContent propsRef={propsRef} />
    </MascotClient>
  </MascotProvider>
), []); // refs are stable — no re-renders
```

2. **Dispatch to a context** instead of calling parent callbacks directly from tool handlers — this is the pattern used in the reference implementation, where tool results update a separate context rather than flowing back as props through the widget tree.