Most WebRTC tutorials end right when things get hard: "and then you connect!" — as if the data channel magically transports your bytes.

I spent three months building TransP2P, a browser-based P2P file transfer tool. No install, no cloud storage, no accounts. What should have been a weekend project turned into a deep dive into how browsers actually handle large files — and how messy that landscape still is in 2026.

Here are the five pitfalls that nearly broke the project, and how I solved each one.

Pitfall 1: The signaling server was the easy part

Everyone warns you about TURN servers. Nobody warns you about the first five minutes.

The signaling flow is straightforward: WebSocket exchange of SDP offers/answers and ICE candidates, then the data channel opens. I got this working in an afternoon.

The problem came from users testing in the real world. Someone on a corporate VPN. Someone behind CGNAT. Someone on Firefox with strict peer-to-peer disabled.

What no one tells you: ICE candidate gathering takes time. Not seconds — sometimes 15-30 seconds on restrictive networks. Without feedback, users assume it's broken and close the tab.

My fix: show a "Connecting..." state with a live counter. Once I added that, support emails dropped significantly. The connection wasn't broken — it was just slow.

Pitfall 2: Safari doesn't support OPFS from a Web Worker

This is the one that cost me two weeks.

I built the file receiving logic using the Origin Private File System (OPFS) — you write chunks directly to disk from a Web Worker, bypass the browser's memory limits, handle multi-gigabyte files without crashing the tab.

Works perfectly on Chrome, Edge, Firefox.

On Safari? Silent failure. Safari doesn't support OPFS access from Web Workers. The code runs, no error thrown, but nothing gets written.

The Safari fallback: IndexedDB for everything — chunks and metadata. It works, but IndexedDB is memory-backed before it flushes to disk, so large files hit a ceiling on iOS specifically.

The honest fix was to show a size warning before the transfer starts, telling the user what their browser can handle. Better than crashing silently.

Pitfall 3: The data channel will reorder your chunks

WebRTC DataChannel has a mode called ordered: true — it guarantees chunks arrive in the order you sent them. Sounds perfect for file transfer.

Except "guarantees" means it will wait. If chunk #47 is lost in transit, chunks #48, #49, #50 all wait in a buffer until #47 is retransmitted. On a bad connection, this can stall a transfer indefinitely.

My first implementation used ordered: true and assumed everything would be fine.

It was not fine.

What I switched to: chunk-level checksums. Each chunk includes a hash. The receiver checks the hash and requests a retransmit only for corrupted chunks — out of order is fine, as long as the data is intact. This is how BitTorrent handles it, and there's a reason.

The tradeoff: I had to implement manual chunk ordering on the receiver side. It's five extra lines of code, but the behavior on spotty connections is dramatically better.

Pitfall 4: Browser memory limits are real and poorly documented

Early versions crashed on files over 500MB. Chrome. On a good laptop.

Why? I was holding chunks in an ArrayBuffer before writing them out. Even though I was chunking the file, I was still holding the reassembled file in memory before saving.

The fix sounds obvious: stream directly to storage. But "directly" means using WritableStream from a Web Worker, writing to OPFS as chunks arrive. No single in-memory object larger than one chunk (64KB).

Once I got this right, I tested with a 4GB file on Chrome. It worked. Memory usage stayed flat at ~80MB throughout.

The lesson: in the browser, you have to be intentional about memory management even when you think the runtime handles it for you.

Pitfall 5: Users don't know what P2P means

This wasn't a technical problem. It was a product problem.

When you explain "your file goes directly to the other person — no server in between," many users hear "your file goes nowhere" or "this can't possibly work."

The transfer was working. The UX was failing.

I spent a week redesigning the "how it works" section — adding a simple three-step visual with a direct line between two browser windows. No cloud servers in the diagram. Just two devices, a line between them.

Downloads from that section increased, and so did completed transfers. Turns out people need to see the connection to trust it.

What I'd tell myself at the start

1. Test on iOS Safari early. Not after launch. It's the hardest browser to support and you'll find issues that won't show up anywhere else.

2. ICE gathering takes time. Show a loading state. Always.

3. ordered: true is not free. Implement your own ordering and checksumming.

4. OPFS from Web Workers is the right approach for large files — but you need a fallback for Safari, and that fallback has limits.

5. The hardest UX problems aren't technical. Explaining P2P to non-technical users took more iteration than the actual P2P implementation.

Try it

TransP2P is live — P2P mode is free, no install, no account. If you've shipped something with WebRTC DataChannels, I'm curious: how did you handle the Safari OPFS problem? That's the one I'm still not fully satisfied with.