WebTorrent Client

Common errors

• Uncaught Error: Error downloading torrent: XHR error

  cause This error often occurs in browser environments when trying to fetch a .torrent file from a URL without proper CORS (Cross-Origin Resource Sharing) headers from the server.
  fix Ensure the server hosting the .torrent file has `Access-Control-Allow-Origin` headers configured to permit requests from your domain.

• No peers found

  cause In a browser, this typically means there are no WebRTC-compatible seeders for the given torrent. Traditional BitTorrent peers are not visible to browser clients.
  fix Verify that the torrent is being seeded by a client that supports WebTorrent/WebRTC (e.g., WebTorrent Desktop, instant.io).

• The torrent ID format is invalid. Supported formats: Magnet URI: magnet:?xt=urn:btih:... Info hash: 08ada5a7a6183aae1e09d831df6748d566095a10. HTTP URL to .torrent file: https://example.com/file.torrent. File path (Node.js only): /path/to/file.torrent. Buffer (Node.js only): Buffer containing .torrent file.

  cause The input provided to `client.add()` does not match one of the supported torrent identifier formats.
  fix Double-check the magnet URI, info hash, or URL for correctness and ensure it adheres to the specified formats. For Node.js, file paths and Buffers are also accepted.

• Write to disk: access denied

  cause In Node.js, the WebTorrent client attempted to write downloaded files to a directory where the process lacks write permissions.
  fix Ensure the target download directory (specified in `client.add({ path: './downloads' })`) has appropriate write permissions for the Node.js process. Try using a different, accessible directory or running the process with elevated privileges if necessary.

Warnings

• breaking WebTorrent v2.0+ is ESM-only. CommonJS `require()` syntax is no longer supported and will lead to errors in modern Node.js environments or bundled browser applications.
  Fix: Update imports to use ES module syntax: `import WebTorrent from 'webtorrent'`.
• breaking WebTorrent v2.0+ requires Node.js version 16 or later. Older Node.js versions (12, 14, etc.) are no longer supported and will cause runtime issues.
  Fix: Upgrade your Node.js environment to version 16 or higher.
• breaking The `file.getBuffer()` method has been deprecated and removed in favor of standard Web APIs. Attempts to use it will fail.
  Fix: Use `await file.arrayBuffer()` to get an `ArrayBuffer` or `file.stream()` to get a `ReadableStream` instead.
• gotcha WebTorrent clients running in a web browser can only connect to other WebTorrent-compatible clients (known as 'web peers') that support WebRTC. They cannot directly connect to traditional BitTorrent clients using TCP or UDP, unless a 'hybrid' client acts as a bridge.
  Fix: Ensure the torrent you are trying to download/seed in the browser is being seeded by a WebRTC-capable client (e.g., WebTorrent Desktop, Instant.io, webtorrent-hybrid).
• gotcha Starting with v2.0, WebTorrent in the browser uses persistent storage (File System Access API + IndexedDB) instead of memory-only. This means torrent data can persist across sessions but requires explicit cleanup to free up space.
  Fix: Always call `torrent.destroy()` when you are finished with a torrent to clean up its associated storage.

Install

• npm install webtorrent npm
• yarn add webtorrent yarn
• pnpm add webtorrent pnpm

Imports

• WebTorrent
  wrong:

  const WebTorrent = require('webtorrent')

  correct:

  import WebTorrent from 'webtorrent'

  WebTorrent v2.0+ is ESM-only; CommonJS `require()` is no longer supported.
• WebTorrent.WEBRTC_SUPPORT

  import WebTorrent from 'webtorrent'; const supportsWebRTC = WebTorrent.WEBRTC_SUPPORT

  A static property to check WebRTC support in the current environment.
• Torrent

  import WebTorrent, { Torrent } from 'webtorrent'; // or import type { Torrent } from 'webtorrent' for TS

  The `Torrent` class represents an active torrent download/seeding. It is usually obtained from a `WebTorrent` instance.

Quickstart

This quickstart initializes a WebTorrent client, adds a magnet URI, logs download progress, and saves the torrent's files to a local directory once complete. It includes error handling and proper client cleanup.

import WebTorrent from 'webtorrent';
import fs from 'node:fs';

const client = new WebTorrent();

const magnetURI = 'magnet:?xt=urn:btih:08ada5a7a6183aae1e09d831df6748d566095a10'; // Example Sintel torrent (public domain)

client.add(magnetURI, { path: './downloads' }, (torrent) => {
  console.log(`Client is downloading torrent: ${torrent.infoHash}`);

  torrent.on('download', () => {
    console.log(`Downloaded: ${torrent.downloaded} bytes of ${torrent.length} total`);
  });

  torrent.on('done', () => {
    console.log('Torrent download finished!');
    torrent.files.forEach((file) => {
      console.log(`File name: ${file.name}, length: ${file.length}`);
      // Example: Stream a file to disk (Node.js only)
      const source = file.createReadStream();
      const destination = fs.createWriteStream(`./downloads/${file.name}`);
      source.pipe(destination);
      source.on('end', () => {
        console.log(`Finished writing ${file.name} to disk.`);
      });
    });
    client.destroy(); // Clean up client after download
  });

  torrent.on('error', (err) => {
    console.error('Torrent error:', err.message);
    client.destroy();
  });
});

client.on('error', (err) => {
  console.error('WebTorrent client error:', err.message);
});