Troubleshooting

Common issues and solutions when working with WebTorrent

Browser Issues

No Peers Found

Problem: Browser downloading shows no peers

Symptom: You add a magnet URI or torrent file, but no peers are discovered and downloading doesn’t start.

Solution: The torrent must be seeded by a WebRTC-capable client. WebTorrent in the browser can only connect to other WebRTC peers.

Make sure the torrent is being seeded by:

• WebTorrent Desktop
• Vuze with WebTorrent plugin
• webtorrent-hybrid
• Instant.io
• Another WebTorrent browser instance

Desktop torrent clients like uTorrent, BitTorrent, and Transmission cannot connect to WebTorrent browser clients unless they support WebRTC.

Problem: Peers connect then disconnect immediately

Symptom: Peers are discovered but disconnect after a few seconds.

Common causes:

• CORS issues: Make sure trackers support CORS if you’re using custom trackers
• Network restrictions: Some networks block WebRTC traffic
• Firewall/NAT: The peer may be behind a restrictive firewall

Solutions:

// Add more reliable trackers
client.add(magnetURI, {
  announce: [
    'wss://tracker.openwebtorrent.com',
    'wss://tracker.btorrent.xyz',
    'wss://tracker.fastcast.nz'
  ]
})

Video Streaming Issues

Problem: Video won't play or stream

Symptom: Video element shows black screen or loading spinner indefinitely.

Check browser support:

• Ensure MediaSource API is supported (Firefox 42+, Chrome, Safari, Edge)
• Check if the video codec is supported by your browser

Supported formats:

• ✅ MP4 (H.264/H.265, AAC) - Best support, seeking works
• ✅ WebM (VP8/VP9, Vorbis/Opus)
• ✅ MKV (various codecs)
• ⚠️ Other formats have limited support

Solution:

// Make sure you've registered the service worker first
const controller = await navigator.serviceWorker.register('./sw.min.js', {
  scope: './'
})
await navigator.serviceWorker.ready
client.createServer({ controller })

client.add(magnetURI, torrent => {
  const file = torrent.files.find(f => f.name.endsWith('.mp4'))
  
  if (!file) {
    console.error('No MP4 file found')
    return
  }
  
  const video = document.querySelector('video')
  file.streamTo(video)
  
  video.addEventListener('error', (e) => {
    console.error('Video error:', video.error)
  })
})

Problem: Video stutters or buffers constantly

Symptom: Playback keeps pausing to buffer.

Solutions:

1. Check download speed:

torrent.on('download', () => {
  console.log('Speed:', torrent.downloadSpeed, 'bytes/sec')
  console.log('Progress:', (torrent.progress * 100).toFixed(1) + '%')
})

2. Wait for more pieces before playing:

torrent.on('ready', () => {
  // Wait until 5% is downloaded
  const interval = setInterval(() => {
    if (torrent.progress > 0.05) {
      clearInterval(interval)
      file.streamTo(video)
      video.play()
    }
  }, 1000)
})

3. Increase max connections:

const client = new WebTorrent({
  maxConns: 100 // Default is 55
})

Problem: Video seeking doesn't work

Symptom: Clicking on the progress bar doesn’t jump to that position.

Solution: Only MP4 files have full seeking support. For other formats, seeking may be limited.

If using MP4 and seeking still doesn’t work:

// Ensure service worker is properly set up
const controller = await navigator.serviceWorker.register('./sw.min.js', {
  scope: './' // Must match the scope where your page is served
})
await navigator.serviceWorker.ready

// Verify the server is created
const server = client.createServer({ controller })
console.log('Server created:', server)

Service Worker Issues

Problem: Service Worker registration fails

Symptom: navigator.serviceWorker.register() throws an error.

Common causes:

• HTTPS required: Service Workers only work on HTTPS (or localhost)
• Scope mismatch: Service Worker file must be at or above the scope path
• File not found: sw.min.js is not being served correctly

Solutions:

1. Use HTTPS or localhost:

# For development, use localhost
npx serve -l 3000
# Access via http://localhost:3000

2. Check file path:

// sw.min.js must be in the root directory or above your HTML file
const controller = await navigator.serviceWorker.register('./sw.min.js', {
  scope: './' // Scope must be at or below sw.min.js location
})

3. Copy service worker file:

# Copy from node_modules
cp node_modules/webtorrent/sw.min.js public/sw.min.js

Problem: Service Worker installed but streaming doesn't work

Check service worker is active:

const registration = await navigator.serviceWorker.register('./sw.min.js')
console.log('Registration:', registration)

await navigator.serviceWorker.ready
console.log('Service Worker is ready')

const server = client.createServer({ controller: registration })
console.log('Server created:', server)

Debug in DevTools:

• Open Chrome DevTools → Application → Service Workers
• Check if the service worker is activated
• Look for errors in the service worker console

Node.js Issues

Problem: Cannot find module 'webtorrent'

Symptom: Error: Cannot find module 'webtorrent'

Solution:

# Install WebTorrent
npm install webtorrent

# For Node.js to connect to WebRTC peers, use hybrid version
npm install webtorrent-hybrid

For ESM projects, ensure package.json has:

{
  "type": "module"
}

Problem: No peers in Node.js

Check DHT and trackers are enabled:

const client = new WebTorrent({
  dht: true,     // Enable DHT
  tracker: true, // Enable trackers
  lsd: true      // Enable local peer discovery
})

client.add(magnetURI, torrent => {
  console.log('Trackers:', torrent.announce)
  
  torrent.on('peer', peer => {
    console.log('Connected to peer:', peer.id)
  })
  
  torrent.on('wire', wire => {
    console.log('Wire protocol established:', wire.remoteAddress)
  })
})

Use webtorrent-hybrid for WebRTC support:

npm install webtorrent-hybrid

import WebTorrent from 'webtorrent-hybrid'
// Now can connect to both TCP/UDP and WebRTC peers

Problem: Port already in use

Symptom: Error: listen EADDRINUSE: address already in use

Solution: Specify different ports:

const client = new WebTorrent({
  dht: {
    port: 6881 // Change DHT port
  },
  tracker: {
    port: 8000 // Change tracker port
  }
})

Memory and Performance Issues

Problem: High memory usage

Solutions:

1. Destroy torrents when done:

torrent.on('done', () => {
  // Wait a bit for final seeding, then destroy
  setTimeout(() => {
    torrent.destroy()
  }, 60000) // Seed for 1 minute
})

2. Limit concurrent torrents:

// Only keep 3 torrents active
if (client.torrents.length > 3) {
  client.torrents[0].destroy()
}

3. Reduce buffer size (Node.js):

const client = new WebTorrent({
  maxConns: 30 // Reduce connections
})

Problem: Slow download speeds

Diagnose the issue:

torrent.on('download', () => {
  console.log('Download speed:', (torrent.downloadSpeed / 1024 / 1024).toFixed(2), 'MB/s')
  console.log('Peers:', torrent.numPeers)
  console.log('Progress:', (torrent.progress * 100).toFixed(1) + '%')
})

Solutions:

1. Increase max connections:

const client = new WebTorrent({
  maxConns: 100
})

2. Add more trackers:

client.add(magnetURI, {
  announce: [
    'wss://tracker.openwebtorrent.com',
    'wss://tracker.btorrent.xyz',
    'udp://tracker.opentrackr.org:1337',
    'udp://tracker.openbittorrent.com:6969'
  ]
})

3. Check for bandwidth throttling:

const client = new WebTorrent({
  downloadLimit: -1, // Unlimited
  uploadLimit: -1    // Unlimited
})

Debugging Tips

Enable Debug Logs

Browser

Open the browser console and run:

localStorage.setItem('debug', '*')
// Then refresh the page

To disable:

localStorage.removeItem('debug')

For specific modules only:

localStorage.setItem('debug', 'webtorrent,bittorrent-dht')

Node.js

Set the DEBUG environment variable:

# All debug logs
DEBUG=* node app.js

# Only WebTorrent logs
DEBUG=webtorrent node app.js

# Multiple modules
DEBUG=webtorrent,bittorrent-dht node app.js

Check WebTorrent Version

import WebTorrent from 'webtorrent'
console.log('WebTorrent version:', WebTorrent.VERSION)

Verify Browser Support

import WebTorrent from 'webtorrent'

if (!WebTorrent.WEBRTC_SUPPORT) {
  console.error('WebRTC is not supported in this browser')
} else {
  console.log('WebRTC is supported!')
}

// Check MediaSource support
if ('MediaSource' in window) {
  console.log('MediaSource API is supported')
} else {
  console.warn('MediaSource API is not supported - streaming may not work')
}

// Check Service Worker support
if ('serviceWorker' in navigator) {
  console.log('Service Worker is supported')
} else {
  console.warn('Service Worker is not supported')
}

Common Error Messages

Error: Torrent is not done

You’re trying to access file data before the torrent is ready.

Solution:

torrent.on('ready', () => {
  // Now you can access files
  torrent.files.forEach(file => {
    console.log(file.name)
  })
})

Error: Unsupported torrent identifier

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

Error: Cannot read property 'files' of undefined

The torrent hasn’t been added successfully or hasn’t loaded yet.

Solution:

client.add(magnetURI, (torrent) => {
  if (!torrent) {
    console.error('Failed to add torrent')
    return
  }
  
  // Use torrent here
  console.log('Files:', torrent.files)
})

// Or handle errors
client.on('error', (err) => {
  console.error('Client error:', err)
})

Getting Help

If you’re still having issues:

1. Search existing issues: GitHub Issues
2. Join the community:
   • Gitter chat
   • IRC: #webtorrent on freenode
3. Create a new issue: Include:
   • WebTorrent version
   • Browser/Node.js version
   • Full error message
   • Minimal reproduction code

When reporting issues, always include debug logs by enabling DEBUG=* (Node.js) or localStorage.setItem('debug', '*') (browser).