Waku v2 handshake timeouts during Kademlia DHT discovery

Question

When deploying Waku v2 nodes, the modular architecture relies on the Kademlia DHT for peer discovery. In high-latency environments, the waku-node logs frequently report dial-timeout errors or peer rejection during the initial handshake. These failures prevent the node from establishing a stable connection to bootstrap nodes or participating in the Gossipsub layer.
There is uncertainty regarding the specific backoff strategy employed by the protocol when encountering these timeouts. This inconsistent behavior makes it difficult to determine if the de-synchronization is due to a configuration mismatch in the network keys or an inherent limitation of the transport layer.
How does the Waku node differentiate between a version mismatch rejection and a network-level packet timeout in the DHT logs? What specific log patterns indicate that the discovery backoff has reached its maximum limit before failing the deployment?

Tasadduq Burney · Answer

How Waku v2 distinguishes version‑mismatch from network timeout
The node first attempts a dial to the peer. If the TCP/UDP connection cannot be established within the configured dial timeout, libp2p logs a pure dial‑timeout entry (e.g., error=dial-timeout or failed to dial peer … within timeout) without any mention of protocol version. This indicates a network‑level packet timeout.
If the dial succeeds but the subsequent libp2p handshake fails because the peer advertises an unsupported protocol version, the log contains a version‑mismatch string such as err=handshake failed: unsupported protocol version or peer … rejected: protocol version mismatch. The presence of a version‑specific message after a successful dial is the distinguishing signal.
Log pattern that shows the discovery backoff has reached its limit
When the adaptive exponential backoff (with jitter) hits its configured maximum, you will see a series of dial‑timeout logs for the same peer where the delay value roughly doubles each attempt (e.g., backoff=2s, backoff=4s, backoff=8s …) until it stabilizes at the max (commonly 30 s). After the final attempt the node logs a giving‑up message, for example:

giving up on peer  after max retries
backoff limit reached, ceasing further dial attempts for

Seeing this sequence confirms that the backoff algorithm has exhausted its retry budget and the deployment will not proceed until the delay is reduced or network latency improves.
Verification steps for this specific case

Enable debug logging for the libp2p subsystem (e.g., start the node with LOG_LEVEL=debug or the equivalent flag).
Reproduce the high‑latency condition (network throttling, artificial delay, or a real‑world congested link).
Watch the log stream for a peer that repeatedly shows error=dial-timeout without any version‑mismatch text.
Measure the interval between successive timeout entries for that peer; verify that the delay approximately doubles (with jitter) until it stops increasing.
Look for the final “giving up” or “backoff limit reached” line; note the observed max delay and compare it to the node’s configured timeout (often exposed via --libp2p-timeout or similar).

If you are using a custom logger that renames the fields (e.g., msg= instead of error=), the semantic content remains the same; adjust the grep pattern accordingly.

Waku v2 handshake timeouts during Kademlia DHT discovery

1 answer

How Waku v2 distinguishes version‑mismatch from network timeout

Log pattern that shows the discovery backoff has reached its limit

Verification steps for this specific case

Your perspective belongs here.

0 question comments