From 68961c89ca0f1f3a4dd21b22ee618b2041f4f2dd Mon Sep 17 00:00:00 2001 From: Galoretka Date: Thu, 14 Aug 2025 16:38:19 +0300 Subject: [PATCH 1/3] docs: add TROUBLESHOOTING.md --- doc/TROUBLESHOOTING.md | 142 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 doc/TROUBLESHOOTING.md diff --git a/doc/TROUBLESHOOTING.md b/doc/TROUBLESHOOTING.md new file mode 100644 index 0000000000..d9578ab39b --- /dev/null +++ b/doc/TROUBLESHOOTING.md @@ -0,0 +1,142 @@ +# Troubleshooting + +This guide lists common issues you may encounter when running `js-libp2p`, along with steps to diagnose and resolve them using existing logs, events and configuration. + +## Enable debug logging + +- Node: + +```bash +# all libp2p debug logs +DEBUG="libp2p:*" node my-script.js + +# focus on connection dialing and common network components +DEBUG="libp2p:connection-manager:dial-queue,libp2p:tcp,libp2p:websockets,libp2p:webtransport,libp2p:kad-dht" node my-script.js +``` + +- Browser: + +```js +// all libp2p debug logs +localStorage.setItem('debug', 'libp2p:*') + +// focus on connection dialing and common network components +localStorage.setItem('debug', 'libp2p:connection-manager:dial-queue,libp2p:websockets,libp2p:webtransport,libp2p:kad-dht') +// then refresh the page +``` + +Logger namespaces used by components include: + +- `libp2p:tcp` (`@libp2p/tcp`) +- `libp2p:websockets` (`@libp2p/websockets`) +- `libp2p:webtransport` (`@libp2p/webtransport`) +- `libp2p:kad-dht` (`@libp2p/kad-dht`) +- `libp2p:connection-manager:dial-queue` + +## Common issues + +### No transport available for address + +Symptoms: + +- Error originating from the transport manager similar to: + +```text +No transport available for address //... +``` + +This occurs when you try to listen on or dial a Multiaddr for which no transport is configured. For example, `/ip4/127.0.0.1/tcp/0` requires `@libp2p/tcp`, `/ws` requires `@libp2p/websockets`, and `/webtransport` requires `@libp2p/webtransport`. + +Actions: + +- Ensure the corresponding transport is added to `transports` when creating the node. +- Verify the Multiaddr protocol matches an enabled transport. +- Enable component logs to see selection and listen errors: + +```bash +DEBUG="libp2p:tcp,libp2p:websockets,libp2p:webtransport" node my-script.js +``` + +### Address reported as not dialable / dial failed + +Symptoms: + +- Dial attempts fail with logs like: + +```text +libp2p:connection-manager:dial-queue dial failed to +``` + +- Downstream components may log messages such as "could not dial". + +Actions: + +- Check that the peer’s addresses include a protocol supported by your configured transports. +- Verify the address formatting (see next section) and that any required intermediaries (e.g. relays) are reachable. +- Increase dial logs: + +```bash +DEBUG="libp2p:connection-manager:dial-queue,libp2p:tcp,libp2p:websockets,libp2p:webtransport" node my-script.js +``` + +### Invalid Multiaddr format + +Symptoms: + +- Errors like: + +```text +Can't convert to IpNet, Invalid multiaddr format: +``` + +Actions: + +- Validate that the string is a correct Multiaddr. Construct addresses using `@multiformats/multiaddr` where possible to avoid typos. +- Ensure all required protocol parts are present (e.g. `/ip4/.../tcp/...`, `/dns4/.../tcp/.../ws`). + +### WebTransport cannot listen in Node.js + +Symptoms: + +- Attempting to listen using WebTransport fails. + +Context: + +- The WebTransport transport currently only supports dialing to other nodes. Listening requires QUIC support to land in Node.js first. + +Actions: + +- Use WebTransport for dialing only. For listening in Node.js, use supported server-side transports such as TCP or WebSockets. + +### Peer discovery does not emit events + +Symptoms: + +- You do not see `peer:discovery` or subsequent `peer:connect` events. + +Actions: + +- Ensure at least one discovery module is configured (e.g. `@libp2p/bootstrap`, `@libp2p/mdns`). +- Listen for events to verify activity: + +```ts +node.addEventListener('peer:discovery', (evt) => { + console.log('Discovered', evt.detail.id.toString()) +}) + +node.addEventListener('peer:connect', (evt) => { + console.log('Connected to', evt.detail.toString()) +}) +``` + +- Enable discovery-related logs (for example, DHT and transports) to see find/dial attempts: + +```bash +DEBUG="libp2p:kad-dht,libp2p:tcp,libp2p:websockets,libp2p:webtransport" node my-script.js +``` + +## See also + +- `doc/GETTING_STARTED.md` Debugging section for quick debug setup +- `doc/CONFIGURATION.md` for full configuration options +- `doc/API.md` Events section (`peer:discovery`, `peer:connect`) From f4ceaf9fc77d0822b394a8adb23998750586cb48 Mon Sep 17 00:00:00 2001 From: Galoretka Date: Thu, 14 Aug 2025 16:38:46 +0300 Subject: [PATCH 2/3] docs: add TROUBLESHOOTING.md and extend Debugging section --- doc/GETTING_STARTED.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/GETTING_STARTED.md b/doc/GETTING_STARTED.md index 56c0322ec0..f663549e60 100644 --- a/doc/GETTING_STARTED.md +++ b/doc/GETTING_STARTED.md @@ -259,7 +259,7 @@ When running libp2p you may want to see what things are happening behind the sce DEBUG="libp2p:*" node my-script.js # networking debug logs -DEBUG="libp2p:tcp,libp2p:websockets,libp2p:webtransport,libp2p:kad-dht,libp2p:dialer" node my-script.js +DEBUG="libp2p:tcp,libp2p:websockets,libp2p:webtransport,libp2p:kad-dht,libp2p:connection-manager:dial-queue" node my-script.js ``` ### Browser @@ -269,9 +269,11 @@ DEBUG="libp2p:tcp,libp2p:websockets,libp2p:webtransport,libp2p:kad-dht,libp2p:di localStorage.setItem('debug', 'libp2p:*') // then refresh the page to ensure the libraries can read this when spinning up. // networking debug logs -localStorage.setItem('debug', 'libp2p:websockets,libp2p:webtransport,libp2p:kad-dht,libp2p:dialer') +localStorage.setItem('debug', 'libp2p:websockets,libp2p:webtransport,libp2p:kad-dht,libp2p:connection-manager:dial-queue') ``` +See also: [TROUBLESHOOTING.md](https://github.com/libp2p/js-libp2p/blob/main/doc/TROUBLESHOOTING.md) for common issues and diagnosis steps. + ## React Native Libp2p can be used in React Native applications. However, there are some limitations and considerations to take into account as not all transports are supported and some of the underlying dependencies may not work as expected. There is on-going work to address these issues, particularly around the support of TCP. For a demo on how to use libp2p in a React Native application, see https://github.com/ipfs-shipyard/js-libp2p-react-native From 6226497bbc86217f7505242295b2f457b6d20958 Mon Sep 17 00:00:00 2001 From: Galoretka Date: Tue, 9 Sep 2025 09:31:26 +0300 Subject: [PATCH 3/3] Update TROUBLESHOOTING.md --- doc/TROUBLESHOOTING.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/TROUBLESHOOTING.md b/doc/TROUBLESHOOTING.md index d9578ab39b..80a0754a99 100644 --- a/doc/TROUBLESHOOTING.md +++ b/doc/TROUBLESHOOTING.md @@ -94,19 +94,20 @@ Actions: - Validate that the string is a correct Multiaddr. Construct addresses using `@multiformats/multiaddr` where possible to avoid typos. - Ensure all required protocol parts are present (e.g. `/ip4/.../tcp/...`, `/dns4/.../tcp/.../ws`). -### WebTransport cannot listen in Node.js +### WebTransport is not supported in Node.js Symptoms: -- Attempting to listen using WebTransport fails. +- Attempting to configure, dial, or listen using WebTransport in Node.js does not work. Context: -- The WebTransport transport currently only supports dialing to other nodes. Listening requires QUIC support to land in Node.js first. +- In Node.js the WebTransport API is not available, so the transport does not enable dialing (it checks for a global `WebTransport`) and does not support listening. Actions: -- Use WebTransport for dialing only. For listening in Node.js, use supported server-side transports such as TCP or WebSockets. +- Do not use WebTransport in Node.js. Use supported transports such as TCP or WebSockets. +- Use WebTransport only in environments that provide a `WebTransport` implementation. ### Peer discovery does not emit events