Debugging

Tools and techniques for debugging Passage Connect sessions.

Debug WebSocket

Connect as a debug viewer to observe all messages in real time:

GET /sessions/:id/ws?role=debug&token=DEBUG_TOKEN

Debug connections receive all messages wrapped in envelopes with direction and timestamp:

{
  "direction": "worker_to_server",
  "message": { "type": "worker.command", ... },
  "ts": "2025-01-01T00:00:01Z"
}

Retrieving events

Fetch the full event log for a session:

GET /v1/sessions/:id/events

Events include navigation, network responses, and console messages from the webview.

Common issues

Session stuck in “pending”

Only one side (client or worker) has connected. Verify both connections are established.

Command timeout

The client did not respond to a command. Check that the client SDK is connected and the webview is loaded.

Yield not resolving

The expected condition hasn’t been met. Check the event log for matching events and verify your condition patterns.

Connection closed with code 4000

The server received a message that is not valid JSON or is missing the type field. Ensure all messages are well-formed JSON objects with a type string.

Authentication errors

Verify your API key and session tokens are correct and not expired. Note that the debug role uses the worker token, not a separate debug token.

Next steps

• Protocol: WebSocket — Connection details
• Protocol: Messages — Message reference