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:

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

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

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)
• Error messages from browser console
• Session ID (if available)
• Steps to reproduce