Diagnosing Silent Waku Subscriptions: A Step‑by‑Step Guide

Problem Statement

You have a Waku node set up to subscribe to waku://example/topic, but the application logs show no incoming messages. The node is running, the publisher is active, and the network appears functional. The issue is often a silent drop caused by a configuration mismatch or network barrier.

Root Causes and Quick Checks

Cause	Typical Symptom	Quick Check	Immediate Fix
Topic string mismatch (case‑sensitive)	No messages, no log errors	Verify the exact string in publisher and subscriber code.	Align the strings; re‑deploy the subscriber.
Relay node unreachable or misconfigured	Subscriber log shows "relay unreachable" or no peers.	Run waku-cli relay status from the subscriber.	Correct the relay address or restart the relay.
Message TTL too low	Messages appear in logs but never arrive.	Send a test message with a known TTL and timestamp.	Increase TTL (e.g., to 30 seconds) in publisher config.
Subscriber not connected to libp2p swarm	Log shows "peer not found" or empty peer list.	Run waku-cli peer ls or p2p ping.	Ensure the node has a valid multiaddress and is bootstrapped.
Network partition or NAT traversal issue	All peers appear unreachable; no logs of message attempts.	Check firewall rules and STUN/TURN configuration.	Open required ports or configure a TURN server.

Diagnostic Workflow

1. Confirm Topic String

   Publish and subscribe code must use the exact same topic. Topics are case‑sensitive and whitespace‑sensitive.

   // Publisher (Node A)
   const topic = "waku://example/topic";
   waku.publish(topic, payload, { ttl: 30 });
   
   // Subscriber (Node B)
   const topic = "waku://example/topic";
   waku.subscribe(topic, onMessage);
   

   If the strings differ, even by a trailing space, the subscriber will never receive the message.

2. Check Relay Connectivity

   From the subscriber node run:

   waku-cli relay status
   

   Expected output: a list of connected relays. If the list is empty or shows an error, update the --relay flag or environment variable to point to a reachable relay (e.g., /ip4/127.0.0.1/tcp/4000/p2p/QmRelayPeerID).

3. Verify TTL Settings

   Publish a test message with a known TTL:

   waku-cli publish --topic waku://example/topic --ttl 5 --payload "test" --to "waku://example/topic"
   

   Observe the subscriber logs. If the message never arrives, increase the TTL or remove the --ttl flag to use the default (e.g., 60 s).

4. Ensure Swarm Membership

   Run a libp2p connectivity test:

   waku-cli peer ls
   

   If the output shows no peers, the node has not joined the swarm. Check the bootstrap list and make sure the node’s multiaddress is reachable from the network.

5. Inspect Network Paths

   Use p2p ping against a known peer:

   p2p ping /ip4/192.0.2.1/tcp/4000/p2p/QmPeerID
   

   Failure indicates a firewall or NAT blocking the connection. Verify that TCP/UDP 4000 (or the configured port) is open and that any required STUN/TURN servers are reachable.

Escalation Criteria

• If all local checks pass but messages still don’t arrive, consider a network-wide traceroute between publisher and subscriber IPs.
• Check for rate limiting or message drops on the relay by reviewing its logs for back‑pressure warnings.
• If the issue persists across multiple topics, the problem may lie in the relay’s configuration or the underlying libp2p stack; open a support ticket with the relay maintainer.

Practical Verification

After applying a fix, re‑run the test publish command and verify that the subscriber logs contain Message received: test within the TTL window. If the message appears, the problem is resolved. If not, revisit the corresponding step in the workflow.

Limitations

• Relay nodes may enforce topic‑based access control; ensure the subscriber is authorized.
• Changing TTL can reduce bandwidth efficiency; use the minimal TTL that satisfies your latency requirements.
• Restarting a node clears in‑flight messages; coordinate with other services if they depend on real‑time delivery.