Introduction

When a realtime avatar fails to connect, the symptom is usually misleading. You see a blank player, a frozen face, one-way audio, or a session that starts and then silently dies. The root cause might be anywhere in the chain: your app, the WebSocket control plane, media negotiation, TURN/STUN reachability, browser autoplay policy, or a bad session payload. The fastest way to debug it is to correlate what your application did with what the SDK and transport layers actually reported.

This post shows a practical debugging workflow for WebRTC and WebSocket issues using Protoface Python SDK logs. By the end, you should be able to tell whether a failure is caused by auth, signaling, media transport, or an application-level configuration problem, and you should know what to look for in logs before you escalate to support or start rewriting code.

Start with the failure mode, not the stack trace

Realtime avatar systems usually have two separate paths:

• Control/signaling path: HTTP requests and WebSocket messages to create sessions, exchange metadata, and coordinate startup.

• Media path: WebRTC audio/video transport, which depends on ICE, STUN/TURN, SDP exchange, codec negotiation, and browser permissions/autoplay behavior.

Those layers fail differently, and logs reflect that. A good first pass is to classify the symptom:

• Immediate 401/403: auth, expired key, bad origin, or malformed request.

• WebSocket connects, then closes: handshake, payload validation, or backend-side rejection.

• Session starts, but no audio/video: WebRTC negotiation or media permissions.

• Video appears but lip sync is off: application timing, audio pipeline delay, or codec/packetization issues.

• Works locally, fails in prod: network policy, CORS/origin allowlist, firewall, or browser autoplay differences.

Don’t start by staring at every log line. Start by answering: did I fail before signaling, during signaling, or after ICE connected?

Turn on structured logging and keep a correlation ID

The most useful logs are the ones you can correlate across your app, the SDK, and the server. For debugging, log at least:

• session ID or request ID

• avatar ID

• timestamps for request start, WebSocket open, ICE state transitions, and first frame/audio

• HTTP status codes and WebSocket close codes

• any SDP/ICE state changes reported by the client

If you are using the Python SDK, enable debug logging early and keep the output in your app logs, not just stdout. Exact API names can vary by version, but the pattern should look like this:

import logging

import logging

import logging

For browser or frontend debugging, preserve the server-generated identifiers in your own logs. If you can’t tie a client-side WebRTC failure back to a specific session, you lose most of the diagnostic value.

Read WebSocket logs like a protocol trace

WebSocket errors are usually easier to isolate than media problems because they happen before audio/video starts. A healthy sequence looks roughly like: HTTP upgrade succeeds, the socket stays open, application messages flow, and the server sends a session-ready or similar event. If the socket closes early, inspect the close code and timing.

Some common patterns:

• 401/403 during upgrade or first request: invalid API key, missing bearer token, expired credentials, or auth mismatch between environments.

• 400-series after the socket is open: request schema mismatch, missing required session fields, or unsupported parameter values.

• 101 upgrade succeeds, then immediate close: server accepted the socket but rejected the session payload.

• Reconnect loops: your client retries too aggressively, the backend is rate limiting, or the socket is being killed by an upstream proxy.

From a shell, isolate the control plane first. If your session creation is via REST, verify that it works independently of your app:

curl -sS https://api.protoface.com/v1/sessions \

curl -sS https://api.protoface.com/v1/sessions \

curl -sS https://api.protoface.com/v1/sessions \

If the REST request fails, the problem is upstream of WebRTC. If it succeeds but the live session still fails, the bug is usually in signaling, client state, or network conditions.

Debug WebRTC by watching ICE, SDP, and media state transitions

WebRTC failures often masquerade as “the avatar is broken,” but the logs usually point to a narrower cause. The states that matter most are:

• ICE gathering: the client is collecting candidates. Failure here suggests permission, network, or local stack issues.

• ICE checking: candidates are being tested. Repeated failure often means NAT traversal or firewall restrictions.

• Connected: transport is up, but media can still fail if tracks are muted, autoplay is blocked, or the remote stream never starts.

• Disconnected / failed: transport was established and then lost, often due to network changes, proxy timeouts, or TURN problems.

In browser DevTools, keep an eye on the peer connection state and the remote track events. In Python, your SDK or integration layer should expose similar hooks or logs. You are looking for questions like:

• Did SDP offer/answer exchange finish?

• Did ICE ever reach connected/completed?

• Did the remote video track attach?

• Did audio start but the page suppress playback because the user didn’t interact?

Two common gotchas:

1. Autoplay: video may render only after a user gesture, even when WebRTC is healthy.

2. Network policy: corporate proxies and restrictive firewalls often allow WebSocket but block UDP, which breaks media while leaving signaling intact.

If you see WebSocket logs that look healthy but ICE never connects, stop debugging the application payload and focus on transport. That saves a lot of time.

Use the SDK logs to separate your bug from the transport bug

One of the most useful things the Python SDK can do is make the boundary between your code and the realtime transport visible. When you wrap session creation, streaming setup, or event handlers with explicit logging, you can tell whether the failure is in your code path or in the remote service.

A practical pattern is to log state transitions and exception boundaries:

try:

try:

try:

Then, when the connection opens, log the first sign of media activity. If you never see the “connected” or “track attached” equivalent, the issue is below your application layer. If you do see it and the avatar still appears frozen, you’re likely dealing with rendering, muted playback, or a stale client state machine.

For deeper debugging, keep these distinctions in mind:

• Transport up, app silent: your event handlers may not be attached, or your session logic never sent the expected message.

• Transport down, app thinks it is up: your state machine is optimistic and not listening for disconnects.

• Repeated session creation: often means your UI is recreating the session on every render or retry, which looks like a backend bug but isn’t.

How Protoface helps when you need a clean signal path

Protoface is built around a few surfaces that keep debugging sane. If you are using the Python SDK or the LiveKit plugin, you can keep avatar/session setup close to your voice-agent code and observe the logs in the same process, instead of chasing state across multiple services. The REST API is also useful for isolating whether session creation itself works before you test media playback.

For example, if your LiveKit agent starts talking but the avatar never appears, the bug is likely in the media integration rather than in session creation. The LiveKit plugin and the Pipecat integration guide are good references for understanding where the avatar is attached in the pipeline; the plugin code and examples on GitHub are especially useful when you want to compare your integration against a known-good path. For documentation and exact request fields, use the docs and, for Python integration details, the Python SDK repository.

Conclusion

Most WebRTC and WebSocket bugs are not mysterious once you separate signaling from media and read logs with that boundary in mind. If you know whether the failure happens at auth, WebSocket upgrade, session negotiation, ICE, or playback, you can usually narrow it down in minutes rather than hours.

The workflow is simple: validate REST/session creation, inspect WebSocket close codes, watch ICE and media state transitions, and preserve correlation IDs so every layer can be tied back to one session. If you want the exact SDK calls, event names, and integration examples for your stack, start with docs.protoface.com and the relevant quickstart in the GitHub org. That will usually get you from “it doesn’t work” to a specific fixable cause quickly.