Skip to main content

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.

​
Module Resolution Issues in Next.js Pages Router

If you encounter errors like: 
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:
/** @type {import("next").NextConfig} */
const nextConfig = {
  transpilePackages: ["@mascotbot-sdk/react"]
}
module.exports = nextConfig
  1. If you’re still seeing issues, try clearing your Next.js cache:
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(() => ..., []):
const propsRef = useRef(props);
propsRef.current = props;

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