How to Debug your Waku dApp #
Enable Debug Logs #
JS-Waku and its most relevant dependencies (libp2p) uses debug to handle logs.
To enable debug logs when running js-waku with NodeJS, simply set the
DEBUG environment variable.
To only enable js-waku debug logs:
To enable js-waku and libp2p debug logs:
To enable all debug logs:
To see the debug logs in your browser’s console, you need to modify the local storage and add
Here are guides for some modern browsers:
||enable js-waku debug logs|
||enable js-waku and libp2p debug logs|
||enable all debug logs|
Check Websocket Setup #
Nwaku natively supports WebSocket (ws) and WebSocket Secure (wss).
These are currently the only transports supported to connect to the Waku network from a browser.
Modern browsers are restrictive with the usage of WebSocket:
- Within a secure context insecure subroutines are disallowed:
wssconnections are allowed, not
- Certificate validation checks are the same for
wss: Certificate must not be expired, certificate needs to come from a CA recognize by the browser or system (no self-signed cert, no ip cert), domain name must match, etc,
- Subroutines errors are not displayed to the user: If a WebSocket connection fails, the user will not be informed, you need to check the browser’s console.
Finally, these rules do not apply if the webpage is served locally (ie, on
If you have difficulties to connect to a remote node via
1. Check that the certificate is valid by opening the
wss connection directly in the browser:
If the multiaddr is
/dns4/nwakunode.com/tcp/1234/wss/p2p/16... then open
https://nwakunode.com:1234 in a modern browser.
If you get a certificate error, then check why the browser returns this certificate error as this is the issue.
If you get a blank page, or any other error, go to step 2.
2. Try to connect with
Check if you can connect to the WebSocket port using
(assuming multiaddr is
websocat -v wss://nwakunode.com:1234 # ... /multistream/1.0.0
If the last line is
/multistream/1.0.0 then it works! In this case, the issue might be somewhere in your code.
Do not hesitate to get support on the Vac Discord.
If you get an error, try with option
-k, --insecure Accept invalid certificates and hostnames while connecting to TLS:
websocat -vk wss://nwakunode.com:1234 # ... /multistream/1.0.0
If it works, then your certificate being invalid is the issue.
If it does not work then indeed, your nwaku node does not accept WebSocket connections, go to 3 for a last check.
3. Verify the WebSocket port is accessible:
telnet (or any other networking tool) to check that the WebSocket port is indeed open and accessible:
(assuming multiaddr is
telnet nwakunode.com 1234 Trying 188.8.131.52... Connected nwakunode.com. Escape character is '^]'
CTRL-] to escape).
If this does not work then ensure the WebSocket port is open.