WebTorrent shows no peers? Check WebRTC seeders before changing settings

When WebTorrent shows no peers in a browser, first check whether anyone is seeding that torrent through a WebRTC-capable client. A torrent can have ordinary BitTorrent seeders and still have none your browser can connect to. Browser WebTorrent uses WebRTC data channels—not the TCP/uTP connections used by ordinary torrent peers. WebTorrent’s FAQ identifies this compatibility requirement in its troubleshooting advice for browser downloads finding no peers.

Work through compatibility, discovery and connectivity in that order. Use only files you have the right to download and share.

1. Identify which WebTorrent environment you are using

The same name covers different connection capabilities:

• WebTorrent running inside a website: connects to WebTorrent/WebRTC-capable peers, not ordinary TCP/uTP peers.
• The standard webtorrent package in Node.js: talks to ordinary torrent clients using TCP and UDP; the project directs developers to webtorrent-hybrid when they also need browser-peer connectivity.
• WebTorrent Desktop: supports both web peers and ordinary BitTorrent peers.

See the WebTorrent project README for the browser/Node.js distinction and the Desktop documentation for its dual-peer support. A desktop download succeeding does not establish that the same torrent has browser-compatible seeders.

For a browser download, ask the publisher whether an active WebRTC-capable client is seeding the exact torrent. If not, use a suitable desktop BitTorrent client for the lawful download, or ask the publisher to provide web-compatible seeding. Adding trackers cannot turn a TCP-only seeder into a WebRTC peer.

Run a controlled browser test

If you cannot verify the publisher’s seeder, test with a small, non-sensitive file you own:

1. Open Instant.io and choose or drag in the file to begin seeding.
2. Keep that page open. Copy the generated magnet link into Instant.io on a second device.
3. Check whether the second device receives the file. If possible, repeat with one device on a different network.

Instant.io provides browser-based seeding and downloading. This test gives you a known web-compatible sender instead of relying on an unknown swarm. A successful test points toward the original torrent’s availability or the original app’s configuration; failure means you should also investigate discovery and connectivity. Remember that WebTorrent downloads automatically seed received data.

2. Check WebSocket tracker discovery

Browser WebTorrent normally discovers peers through WebTorrent-compatible WebSocket trackers. An ordinary HTTP, HTTPS or UDP tracker is not a substitute: discovery must exchange the WebRTC connection information needed by web peers. The project explains this in its tracker-discovery discussion.

Check the tracker list actually used by the app, not just the visible magnet link:

• Is there a WebTorrent-compatible wss:// tracker?
• Is the sender announcing the same info-hash to at least one tracker the receiver also uses?
• Has the application disabled trackers with tracker: false?
• Does the browser console show connection errors or security warnings?

WebTorrent’s API allows an app to add trackers through client.add(torrentId, { announce: [...] }), so a magnet without a visible tr= parameter is not proof that the application has no trackers. Inspect torrent.announce when debugging your own integration. API reference

On an HTTPS website, use a tracker endpoint that actually supports secure WebSockets (wss://). Do not disable mixed-content protection or assume changing ws:// to wss:// will make an unsupported server work. MDN’s WebSocket guidance recommends HTTPS pages with secure WebSocket connections.

Enabling DHT is not the browser fix. The browser build excludes Mainline DHT and ordinary ut_pex; those features cannot supply a TCP connection path to browser peers. See the project’s browser package mappings.

3. Separate tracker access from peer connectivity

Reaching a tracker does not guarantee that two browsers can establish a data channel. WebRTC uses ICE to find a workable network path, with STUN for address discovery and TURN for relay connectivity when a direct path cannot be established. Firewalls and NAT restrictions can prevent direct connections. MDN’s WebRTC protocol overview

For the controlled test above:

• Try a current browser or a clean browser profile to isolate extensions and modified settings.
• Check whether privacy settings or extensions have disabled WebRTC. Do not remove protections blindly; decide whether peer-to-peer sharing is acceptable before enabling it.
• Compare an approved alternative network. If the same sender and torrent work there, investigate the failing network’s policy or connectivity rather than editing the magnet hash.

For site developers, the tracker client accepts an rtcConfig object for WebRTC configuration. If your deployment needs TURN, configure a relay service you control or are authorized to use; adding more torrent trackers does not provide that relay. Tracker client documentation

4. Capture the failure stage in your own app

Attach listeners to the object returned by client.add, rather than waiting for its callback: that callback runs only once metadata is available and the torrent is ready. With your existing client and torrentId, use:

client.on('error', err => console.error('client:', err.message))

const torrent = client.add(torrentId)
torrent.on('warning', err => console.warn(err.message))
torrent.on('error', err => console.error('torrent:', err.message))
torrent.on('noPeers', type => console.log('no peers:', type))
torrent.on('metadata', () => console.log('metadata available'))
torrent.on('wire', wire => console.log('connection:', wire.type))
torrent.on('download', bytes => console.log('received bytes:', bytes))

The API documentation defines noPeers as an event reporting that no peers have been found, with its argument identifying the discovery method that triggered it—not proof that the torrent has no seeders anywhere. Use the other events to narrow the problem:

• No metadata: the client has not yet obtained the file list and piece hashes for the magnet. A publisher-provided .torrent file can supply metadata, but cannot create compatible peers.
• A webrtc wire appears: a browser-peer connection has been established; investigate subsequent transfer errors or piece availability rather than treating discovery as entirely broken.
• Download events occur but playback fails: the problem is no longer simply “no peers.” Check the player integration and browser codec/container support.

An HTTP web seed can provide a fallback for publishers, but it does not supply the missing torrent metadata. For cross-origin browser access, the server needs appropriate CORS headers. See the web-seed creation guide for that separate distribution task.

If you report the failure to the site operator, include the browser version, whether the controlled transfer worked, tracker warnings, whether metadata arrived and whether a webrtc connection appeared. Those details distinguish a missing web seeder from a tracker failure or an unusable network path.