Diagnosing Message Delivery Failures in Waku

The Symptom: Silent Message Loss

In a Waku network, the most common failure mode is not a crash, but a silent failure where a subscriber is connected to the network but receives no inbound messages on a specific topic. Because Waku uses a gossip-based propagation model, messages are dropped by relays or ignored by nodes if the topic filters do not align perfectly.

Diagnostic Matrix: Common Causes

Condition	Likely Cause	Diagnostic Indicator
No messages received on a specific topic	Topic Filter Mismatch	Publisher topic string $\neq$ Subscriber filter string
Messages received intermittently	Gossip/Relay Instability	High latency or 'DROP' events in relay logs
Connection established, zero data flow	Version Incompatibility	Waku v1 node attempting to peer with Waku v2
Messages dropped at the edge	Privacy/Encryption Mismatch	Decryption errors in subscriber application logs

Step-by-Step Verification Process

Follow these checks in order to isolate whether the failure is at the application layer (filters), the network layer (propagation), or the protocol layer (versions).

1. Validate Topic Filter Alignment

Waku relies on exact matches for topic subscriptions. A mismatch in the namespace or a trailing character will result in the node ignoring the message.

• Check: Compare the topic string used by the publisher with the filter registered by the subscriber.
• Verification: Ensure both use the same encoding (e.g., UTF-8) and the same partition ID if using partitioned topics.
• Fix: Update the subscriber's filter to match the publisher's exact topic string.

2. Inspect Relay Propagation

If filters match, the message may be failing to reach the subscriber's node via the relay network.

• Check: Access the logs of the Waku relay node acting as the intermediary.
• Command: Run the following on the relay server (assuming standard log output to stdout):
  grep "PROPAGATE" /var/log/waku-relay.log | grep "[your-topic-name]"
• Risk: High-volume relays may rotate logs quickly; run this check immediately after a failed send attempt.
• Fix: If PROPAGATE events are missing, the issue is upstream from the relay; if they exist but the subscriber sees nothing, the issue is downstream.

3. Verify Protocol Version Consistency

Waku v1 and v2 have fundamental differences in how they handle message routing and filtering. Mixing these versions without a compatibility bridge often leads to silent drops.

• Check: Run the version check on both the publisher and subscriber nodes.
  waku-node --version
• Fix: Ensure both endpoints are running the same major version of the Waku protocol.

Testing the Fix

To verify the resolution, perform a controlled loopback test:

1. Initialize a subscriber on a known unique topic (e.g., test-diag-123).
2. Publish a small payload to that exact topic.
3. Monitor the subscriber's session state. A successful receipt should trigger a state update in the Waku session handler.

Escalation Criteria

If the following conditions are met, the issue is likely a network-level failure rather than a configuration error, and should be escalated to network infrastructure teams:

• Topic filters are verified as identical.
• Node versions are matched.
• Relay logs show PROPAGATE events, but the subscriber node reports no inbound network traffic on the Waku port.
• Basic TCP connectivity (ping/telnet) to the relay is successful, but gossip packets are dropped.