Skip to main content

Debug Your Waku DApp and WebSocket

This guide provides detailed steps to enable and use debug logs to troubleshoot your Waku DApp, whether in a NodeJS or browser environment and check your WebSocket connections in nwaku.

Enabling debug logs​

When resolving issues in your Waku DApp, debug logs can be helpful. The @waku/sdk and libp2p packages use the debug tool to handle and show logs that help you debug effectively.

NodeJS environments​

To enable debug logs for @waku/sdk on NodeJS, you must set the DEBUG environment variable. To only enable debug logs for @waku/sdk:

export DEBUG=waku*

To enable debug logs for both @waku/sdk and libp2p:

export DEBUG=waku*,libp2p*

To enable debug logs for all components:

export DEBUG=*

Browser environments​

To view debug logs in your browser's console, modify the local storage and add the debug key. Here are guides for various modern browsers:

KEYVALUEDESCRIPTION
debugwaku*Enables @waku/sdk debug logs
debugwaku*,libp2p*Enables @waku/sdk and libp2p debug logs
debug*Enables all debug logs

Checking WebSocket setup​

Nwaku provides native support for WebSocket (ws) and WebSocket Secure (wss) protocols. These are the only transports supported for connecting to the Waku Network via browsers.

It's important to note that browsers impose certain limitations on WebSocket usage:

  • Secure Context Requirement: Insecure subroutines are prohibited in secure contexts. On an https:// webpage, only wss connections are permitted, while ws connections are not allowed. This restriction does not apply if the webpage is served locally, like on localhost or 127.0.0.1.
  • Certificate Validation: Certificate validation rules are consistent for https and wss connections. Certificates must not be expired, issued by a recognized Certificate Authority (CA), and match the domain name, among other criteria.
  • User Feedback on Errors: Web browsers do not display errors related to subroutines to the user. If a WebSocket connection encounters an issue, users won't be alerted directly; you'll need to check the browser's console for error details.

If you encounter difficulties when connecting to a remote node using wss, follow these steps:

Try Websocat for connection​

Attempt to connect using websocat, a tool for WebSocket interactions. Test the WebSocket port using the command:

websocat -v wss://[WEBSOCKET HOST]:[WEBSOCKET PORT]

For example, consider a nwaku node with the multiaddr as /dns4/nwakunode.com/tcp/1234/wss/p2p/16...:

$ websocat -v wss://nwakunode.com:1234
# ...
[INFO  websocat::ws_client_peer] Connected to ws

The connection works if the [INFO websocat::ws_client_peer] Connected to ws log entry appears. If not, check that the certificate is valid

Check certificate validity​

Verify the certificate's validity by passing the -k or --insecure flag to handle invalid certificates in websocat:

websocat -v -k wss://nwakunode.com:1234

If this works, the certificate's invalidity is the problem, and you should investigate the cause of the error if not, check if the WebSocket port is accessible.

Check WebSocket port accessibility​

Use telnet or another networking tool to verify if the WebSocket port is open and accessible. For example, if the multiaddr is /dns4/nwakunode.com/tcp/1234/wss/p2p/16..., use the command:

$ telnet nwakunode.com 1234
Trying 123.123.123.123...
Connected to nwakunode.com.
# ...

If the connection succeeds, there might be an issue with nwaku. Consider seeking support on the Waku Discord or raise an issue. If the connection fails, ensure that the WebSocket port is open.