Troubleshooting

Debugging tips

Enable verbose logging

Add error handlers to capture detailed information:

<AvatarCall
  avatarId="customer-service"
  connectUrl="/api/avatar/session"
  onError={(error) => {
    console.error('Avatar error:', error);
    console.error('Error name:', error.name);
    console.error('Error message:', error.message);
    if (error.cause) {
      console.error('Cause:', error.cause);
    }
  }}
/>

Check Session state

Use the useAvatarSession hook to monitor connection state:

import { useAvatarSession } from '@runwayml/avatars-react';

function DebugInfo() {
  const { state, sessionId, error } = useAvatarSession();

  return (
    <pre>
      {JSON.stringify({ state, sessionId, error: error?.message }, null, 2)}
    </pre>
  );
}

Test with minimal setup

Isolate issues by testing with the simplest possible configuration.

React:

npx degit runwayml/avatars-sdk-react/examples/nextjs-simple test-app
cd test-app
npm install
# Add your API key to .env
npm run dev

Not using React:

npx degit runwayml/avatars-sdk-react/examples/vanilla-js test-app
cd test-app
npm install
# Add your API key to .env
npm run dev

See also Not using React? on the integration guide.

If the example works but your integration doesn’t, compare the implementations to find differences.

Webcam, screen share, and permissions

Webcam and screen capture need a secure context (HTTPS or localhost). On plain HTTP (except localhost), the browser may not offer camera or display capture at all.

For component options and examples, see the Webcam & Screen Sharing section of the React SDK README and the integration guide.

Getting help

Resource	Description
Developer Portal	Manage Avatars, view logs, access dashboard
SDK Repository	Report bugs, view examples, check releases
Account Support	Contact your Runway account manager for support

When reporting issues, include:

• Browser and version
• SDK version (npm list @runwayml/avatars-react or npm list @runwayml/avatars)
• Error messages from browser console
• Session ID (if available)
• Steps to reproduce