DEV Community: AiLaoHuYu

What breaks when you self-host a TURN server (coturn — symptom, cause, fix)

AiLaoHuYu — Sun, 20 Sep 2026 03:53:34 +0000

The first article in this series was the traps inside the code. The second was the layer underneath — the candidates that lie, the UDP firewall nobody looks at, the reverse proxy that reaps an idle socket. This one is about the piece people reach for when those two are not enough: the relay.

TURN is the part of WebRTC that gets configured last, in a hurry, by copying a config off a blog post. That is exactly how you end up with a relay that passes every "is it running?" check and still produces no video.

The failures below are all coturn behaviours you can read in the config and the log. What makes them expensive is not that they are subtle — it is that most of them fail without an error message anywhere near where you are looking.

First: is TURN even your problem?

It often is not. Adding a relay to a system whose real fault is elsewhere hides the fault and makes the next debugging session worse.

Three checks, in this order.

Look at which candidate type won. In chrome://webrtc-internals (or about:webrtc in Firefox), find the selected candidate pair and read the local candidate's type. If it says relay, TURN is in the path and working, and your problem is somewhere else entirely. If it says srflx or host while the connection fails, TURN is not being used at all — which is a different bug from TURN being broken, and it lives in your ICE configuration.

Force the relay. In a test page, build the peer connection with iceTransportPolicy: 'relay'. Now TURN is the only permitted path. If this connects while your normal config does not, your relay is fine. If this also fails, you are actually debugging TURN.

Check the two failures from the last article first. A server advertising an unroutable address and a closed UDP media range both produce the same visible symptom as a dead relay: signaling green, ICE stuck checking, then failed. They cost nothing to rule out and they are far more common than a broken coturn.

It says it started and is bound to nothing

Symptom. systemctl start coturn returns success. systemctl status coturn says active. Nothing works.

Cause. On Debian and Ubuntu the package ships /etc/default/coturn with the enable switch commented out, and the start path honours that file. Depending on the version and how the package was installed, that gate is either the init script or a unit that wraps it — and either way you get a clean exit with no error message. A service that declined to start and a service that started and could not bind look identical from systemctl.

This is also where a config file mismatch hides: coturn reads /etc/turnserver.conf by default, but if something passes -c to a different path, your edits are being ignored and nothing tells you.

Check. Do not ask whether the service is running. Ask whether anything is bound.

ss -lunp | grep -E '3478|5349'
journalctl -u coturn -n 50 --no-pager

If the ports are not in the ss output, it is not running in any sense that matters. Note that curl is useless here — TURN is not HTTP, so an HTTP request to 3478 will connect and then produce something unhelpful. It proves nothing either way.

Fix. TURNSERVER_ENABLED=1 in /etc/default/coturn, restart, re-run the check. If it is still not bound, you are now looking at a real startup error and the log will have it.

The relay address points inward

Symptom. The allocation succeeds. The client gets a relayed candidate. The candidate is a 10.x or 172.16–31.x address. ICE never gets past checking, from the outside it looks like the relay is broken, and on the server everything is green.

Cause. A cloud VM's network interface has a private address and the public IP exists in the provider's NAT layer in front of it. The machine has no idea what its public address is. coturn advertises the address it is bound to, so it advertises the private one, and nobody outside can route to it.

This is the same class of bug as the host candidates in the previous article, one layer up: the service is telling the truth about an interface that is a lie.

Fix. Both halves of the mapping:

external-ip=203.0.113.10/10.0.0.4

Public first, private second, slash between them. Setting only the public address is a common half-fix that works until coturn needs to bind locally.

Verify. Re-read the relayed candidate. It should now be the public address, and it should be reachable — which is a different claim, and the next section is why.

You opened the control port and called it done

Symptom. Allocation succeeds. The relayed candidate is correct and public. Media still never flows. Or: it works for one client and not another, with nothing different about them.

Cause. 3478 is the control port. The media does not go over it. coturn allocates a relay port per client from a range — min-port to max-port, default 49152 to 65535 — and the actual RTP flows there, over UDP.

This one is worse than the others because the successful allocation proves your firewall work is partly right, which is exactly the wrong amount of right. You conclude the network is fine and go looking in your application code.

Fix. Open the relay range in both firewalls: the provider's security group and the host's own ufw/iptables. On most cloud providers the security group is the one that actually decides whether a packet arrives and the host firewall is a red herring; on a VPS with a full iptables ruleset it is the reverse. Open UDP. Opening only TCP gets you nothing, because browsers will use UDP for TURN whenever it is available.

Do not narrow the range "for security." This is the trap hidden in a reasonable-sounding hardening step. Each client using the relay takes a port out of the range, and one page can open more than one allocation. A forty-port range is a lab with a handful of users and nothing else, and the way you find out is under load, months later, as an intermittent failure that does not reproduce.

Keep the default range, and if you must narrow it, size it against the number of concurrent clients you expect rather than the number of streams you are picturing.

Nobody can authenticate, and only the log will say why

Symptom. Every allocation is refused. The client retries, or gives up and reports ICE failure. The relay is bound, reachable, and simply will not talk to you.

Cause. coturn has two credential modes and they are alternatives, not layers:

lt-cred-mech is static long-term credentials, with users created through turnadmin. If you enable it and never create a user, every request is refused and there is nothing wrong with your configuration as such.

use-auth-secret with a static-auth-secret is the time-limited REST scheme. The client generates a username of <unix-expiry-timestamp>:<any-label> and a password of base64(HMAC-SHA1(secret, username)). Every part of that has to be exact — the HMAC variant, the encoding, the units of the expiry. Get any of it slightly wrong and you get a refusal that looks exactly like a wrong password, because it is one.

A config that sets neither is, in effect, an unauthenticated relay. That is not a neutral default: it is an open relay, someone will find it, and their traffic will be on your bill and your IP's reputation.

Fix. Pick one mode, set it explicitly, and turn on verbose so the log shows you the request instead of leaving you to infer it. Then generate the credential the way the server expects:

# username = <unix expiry>:<label>;  password = base64(hmac-sha1(secret, username))
EXP=$(( $(date +%s) + 3600 ))
USER="$EXP:demo"
PASS=$(printf '%s' "$USER" | openssl dgst -binary -sha1 -hmac "$SECRET" | openssl base64)
printf 'username=%s\npassword=%s\n' "$USER" "$PASS"

Read the response code, not the symptom. TURN tells you exactly what is wrong if you look at the code in the log:

401 — the challenge. On a first request this is normal and expected; the client is supposed to retry with credentials. Seeing 401s is not itself a fault, and treating it as one sends people down a long road.
441 — wrong credentials. Your HMAC or your expiry is off.
438 — stale nonce. The client cached a nonce past its lifetime; a conforming client retries and you should not see it persist.
403 — forbidden, including a denied peer. See the blocklist section.
486 — allocation quota reached. See the last section.

coturn ships with turnutils_uclient, which does a real allocation against your server and prints what came back. It is the fastest way to test the relay without a browser in the loop at all — check turnutils_uclient -h for the current flags.

The certificate is valid and coturn still cannot read it

Symptom. turn: on 3478 works. turns: on 5349 does not. Or coturn fails to start with a message about a file that definitely exists.

Cause. turns: needs a certificate, coturn runs as its own unprivileged user, and Let's Encrypt's /etc/letsencrypt/live/ directory is symlinks into archive/ behind permissions that user does not have. The certificate is valid, your path is correct, and the process cannot open it.

Fix. Give the turnserver user read access to the cert tree, or have the renewal hook copy the pair somewhere readable with the right ownership. Both work; the second survives a permissions change on the original.

And the part worth more than the fix: turn: on 3478 does not need TLS at all. If what you need is UDP relay for browsers, you can leave turns: out entirely and this whole failure mode stops existing.

There is a second assumption worth killing while you are here: UDP TURN from an HTTPS page is not mixed content. The browser will not block it, and you do not need turns: to satisfy a security policy. It is a common reason people add a certificate they did not need and then spend an evening on permissions.

The blocklist is doing exactly what it was designed to do

Symptom. Allocation succeeds, the candidate is right, the ports are open, and media still does not flow. The log mentions the peer.

Cause. coturn ships with denied-peer-ip entries covering loopback, the private ranges, link-local, multicast and reserved space. This is deliberate and good: it is what stops your relay being used to reach things it should not reach.

But if your peers legitimately live on a private network — a corporate deployment, an internal lab, anything over a VPN — the relay is correctly refusing to talk to them, and it is not going to tell you that it thinks it is protecting you.

Fix. Allow the specific range you need:

allowed-peer-ip=10.20.0.0-10.20.255.255

Be precise about it. The default list is aggressive because a relay will happily connect to whatever it is told to, and you are the one removing that guard for a case where you actually want it removed.

It works until it does not: quotas, TTLs and the bill

Symptom. Clean in testing, degrades in production. Allocations start failing under load. Or the bandwidth graph shows relay traffic far larger than the number of relayed sessions should account for.

Three things, in the order they usually turn out to be:

No quota. coturn's defaults let a single client hold a great deal. total-quota and user-quota cap concurrent allocations, and max-bps caps throughput per session. Without them, one misbehaving client is a capacity incident for everyone else.

Relay traffic is real traffic. Every relayed stream passes through your server, and you pay for it. This is worth watching as a ratio, not a total: what fraction of your sessions needed relay candidates. If it is most of them, you do not have a TURN problem, you have a NAT-traversal problem that you are paying to route around. Treat a rising relay ratio as a defect in your ICE configuration, not as a reason to buy more bandwidth.

Allocation lifetime. Allocations are refreshed by the client. A client that stops refreshing — a throttled tab, a suspended mobile app — loses its allocation at the TTL, and the user experiences that as "it disconnects after a while," which sounds like a media problem and is not one.

The order I would check these in

When a relayed session fails, in this order, cheapest first:

ss -lunp | grep 3478 — is anything actually bound, or did the service decline to start?
Read the relayed candidate's address — public, or a private address nobody can route to?
Confirm the relay UDP range is open in both the provider firewall and the host firewall.
Put verbose in the config, reproduce, and read the TURN response code — 401 on the first request is normal, 441 and 486 are not.
Force iceTransportPolicy: 'relay' in a test page — does it connect when relay is the only permitted path?
Watch the relay ratio — if most sessions relay, the relay is a symptom and not the cure.

One more, and it is the same one as last time because it is the one that keeps being true: test from a network that is not your development machine. Your laptop and your server are often close enough that a path which cannot work anywhere else still works for you. Wifi off, cellular on, open the page on a phone. That is a genuinely different NAT and a genuinely different path, and it is the only test that answers the question you are actually asking.

The kit

I put what I learned into a starter kit: the signaling server and SFU in Go (Pion v4), the browser publisher and viewer, the auto-reconnect chain, the diagnostics panel, deploy files for systemd, Caddy and Docker, and the pitfalls doc with symptom, cause and fix.

There is a live demo you can open without an account, and a canvas self-test page that exercises the whole path and needs no camera: https://lowlatencykit.com

It is paid (early access, Basic $99 / Pro $199 / Team $499, with an early-bird code on the landing page). This article is free, and so are the other two — that part is not a teaser, it is the actual content.

WebRTC works on your laptop. Here is what breaks when you put it on a server.

AiLaoHuYu — Sat, 19 Sep 2026 06:53:11 +0000

The first article in this series covered the traps inside the code — the Pion v4 API changes, the SSRC rewrites, the renegotiation timing. This one is about the layer underneath it, where the failures look identical and have completely different causes.

Everything below happened to me deploying a real-time streaming server to a cloud VM. None of it was a bug in my code, and all of it took longer to find than it should have.

The split that explains most "it connects but there's no video"

Signaling and media take different paths, and only one of them goes through the infrastructure you configured.

Signaling is a WebSocket. It goes out on 443, it is plain TCP, your reverse proxy terminates TLS for it, your tunnel carries it, your certificate covers it, and every tool you already know how to debug applies to it.

Media is RTP over UDP. It goes browser-to-server directly, carrying the actual audio and video. No part of your reverse proxy, your CDN or your tunnel touches it. Not by misconfiguration — by design. A WebSocket connection is not a suitable transport for a 30fps media stream and no proxy is going to turn into one.

So the moment you see a session where the WebSocket is healthy and there is no picture, you are not looking at a bug in your web stack. You are looking at the media path, and the web stack is a red herring. That single distinction has saved me more time than any debugging tool.

The candidate list in your SDP is the whole story of that second path. It is a list of "here is where I might be reachable", and most of the deployment failures below are about that list being wrong.

Trap 1: your ICE candidates are lies

A cloud VM's network interface has a private address. Mine had a 172.31.x.x on the NIC; the public IP exists in the provider's NAT layer in front of it. The machine itself has no idea what its public address is.

So when your server gathers ICE candidates the honest way, it reports what it can see: a private address nobody on the internet can route to. Signaling completes perfectly. ICE checks go out to an unreachable address. You get a connection that never connects, and nothing in any log says why.

There are two ways out, and they are not equivalent:

Use a STUN server. The server asks a public STUN server "what address did this request appear to come from?" and advertises the answer. This is the standard solution and it works — right up until the NAT in front of your VM is the kind that assigns a different external port per destination, at which point the port you advertise is not the port that reaches you, and you are back to failing checks with no explanation.

Tell the server its public IP. If your provider gives you a one-to-one mapping — public IP forwards directly to the instance, same ports — then you can skip the guessing entirely and configure the advertised address explicitly. The candidate your server hands out is then a statement of fact rather than an inference, and it holds regardless of what the NAT is doing.

In Pion that is a setting engine call, made once before you build the API:

se := webrtc.SettingEngine{}
se.SetNAT1To1IPs([]string{opts.PublicIP}, webrtc.ICECandidateTypeHost)
api := webrtc.NewAPI(webrtc.WithSettingEngine(se))

The second is what I ended up using, and the difference on the wire is not subtle. Before, checks that never completed. After, a usable pair with a 7ms round trip and a steady 30fps of decoded frames with zero freezes over a six-second test.

If you take one thing from this section: the fact that your server is behind NAT is not a detail, it is a first-class configuration input you have to handle deliberately. Decide which of the two approaches fits your provider and set it. Do not assume the default gathering will figure it out.

Trap 2: the firewall that has nothing to do with your app

Cloud providers give you two firewalls and only one of them is the one you think of as a firewall.

The one on the machine — ufw, iptables, firewalld — is the one everybody checks. The one at the provider level, usually called a security group, sits in front of the instance and is what actually decides whether a packet arrives. It defaults to closed. On the VM I used, exactly one port was open out of the box: 22.

Now the part that makes this expensive: your web setup gives you no warning at all. You open 443, you get a certificate, the site loads, the signaling connects, and you conclude the networking is done. Almost all of it is done. All of it that runs over TCP is done.

Your media ports are UDP and they are in a range that is not 443, so nothing about a working HTTPS setup tells you anything about them.

The symptom is the one from the previous section and it is maddening: signaling green, ICE stuck in "checking", then failed. Same visible outcome as wrong candidates, completely different fix.

Here is how to tell trap 1 and trap 2 apart, because from the outside they look the same:

Open the browser's WebRTC internals page (chrome://webrtc-internals in Chromium browsers; about:webrtc in Firefox) and look at the candidate list, not the connection state.

If the only candidates you see are private addresses and no public one, you have trap 1 — your server never learned where it really is. If you see a sensible public candidate but the connectivity checks to it are the ones failing, you have trap 2 — the address is right and something is eating the packets.

That is a two-minute check that tells you which of two very different afternoons you are about to have. Learn it before you need it.

Trap 3: your reverse proxy reaps the idle socket

This one is a different failure shape and it is worse, because everything works first.

The WebSocket carries signaling, and signaling is idle most of the time. Two peers agree on parameters, media flows, and then nothing needs to be said for a while. Your reverse proxy has an idle timeout, usually around 60 seconds, and an idle WebSocket looks exactly like an abandoned connection. It closes it.

The tab, meanwhile, has no idea. From the user's perspective the stream is running, the UI says connected, and then something that needed signaling — a reconnection, a new viewer, a track change — goes into a socket that has been dead for a minute.

The fix everyone reaches for first is a heartbeat from the browser: a small message every 30 seconds to keep the socket warm. Do not do this. Background tabs throttle timers, aggressively, and the tab that has been in the background for ten minutes is exactly the one whose heartbeat has stopped. You have built a keepalive that fails precisely when it is needed.

Send the ping from the server instead, at the protocol level rather than the application level. The WebSocket spec defines ping and pong frames, browsers answer pings automatically, and that answer is not subject to the timer throttling that hits your JavaScript. Pair it with a read deadline on the server and you also get something a browser-side heartbeat never gives you: you find out about dead connections within a bounded time instead of discovering them when a room mysteriously gets stuck as busy.

Making the server responsible for liveness also removes a category of bug entirely. There is no client-side code to get wrong, no clock to drift, no timer to be throttled.

The shape of it in gorilla/websocket, with the browser side handling pongs for you with no code at all:

const (
    writeWait  = 10 * time.Second
    pongWait   = 60 * time.Second
    pingPeriod = 25 * time.Second // under pongWait, and under the proxy's own idle limit
)

func (c *Client) writeLoop() {
    ticker := time.NewTicker(pingPeriod)
    defer ticker.Stop()
    for {
        select {
        case msg := <-c.send:
            if err := c.conn.WriteJSON(msg); err != nil { c.close(); return }
        case <-ticker.C:
            if err := c.conn.WriteControl(websocket.PingMessage, nil, time.Now().Add(writeWait)); err != nil {
                c.close(); return
            }
        case <-c.closed:
            return
        }
    }
}

func (c *Client) readLoop() {
    defer c.close()
    _ = c.conn.SetReadDeadline(time.Now().Add(pongWait))
    c.conn.SetPongHandler(func(string) error {
        return c.conn.SetReadDeadline(time.Now().Add(pongWait))
    })
    for {
        var m clientMsg
        if err := c.conn.ReadJSON(&m); err != nil { return }
        _ = c.conn.SetReadDeadline(time.Now().Add(pongWait))
        c.handle(m)
    }
}

Two things worth noticing in that pair. The deadline is refreshed by any inbound frame, not just pongs, so an active connection is never falsely declared dead. And a missed pong closes the client and frees the room, which is why a crashed publisher does not leave the room stuck as busy for the next viewer.

The order I would do this in from scratch

Start with the media path, not the app. Before writing a line of signaling code, answer two questions: which UDP ports will carry media, and are they reachable from the open internet. Both answers come from your provider, not from your code, and finding out later means unpicking an assumption you have built on top of.

Configure the advertised address deliberately, as covered above. Treat "what address does my server claim to be" as a required setting, not something to leave to defaults and hope about.

Test from a network that is not your development machine. This is not a formality. Your laptop and your server are often on networks close enough that a candidate that cannot work anywhere else still works for you. Open the test page on a phone with wifi off and the cellular radio on, and you are testing something genuinely different: a different carrier, a different NAT, and a different path to your server. If it works there, it works.

Only then build reconnection. Reconnection logic on top of a media path that does not work is untestable — every failure looks the same and you cannot tell whether you are debugging your retry logic or the network underneath it.

The kit

There is a live demo you can open without an account, and a canvas self-test page that exercises the whole path and needs no camera: https://lowlatencykit.com

It is paid (early access, Basic $99 / Pro $199 / Team $499, with an early-bird code on the landing page). This article is free, and so is the first one — that part is not a teaser, it is the actual content.

What actually breaks when you build a WebRTC SFU in Go

AiLaoHuYu — Sat, 19 Sep 2026 06:23:39 +0000

Every Pion example I found stops at "hello world": two peer connections, one track, it works, the blog post ends. That is the easy 20%. The other 80% is what happens after — when the publisher's connection drops, when a viewer joins mid-stream, when a reverse proxy reaps your signaling socket, when the person streaming switches browser tabs.

I built a low-latency streaming server: one Go binary doing WebSocket signaling plus SFU forwarding, with a browser publisher, viewer and diagnostics panel. These are the nine things that actually cost me time. Symptoms first, because that is what you will be searching for at 2am.

Spoiler for the whole article: most of these look like a media problem and are not one.

1. `TrackRemote.WriteRTCP` is gone in Pion v4

Symptom: remote.WriteRTCP undefined (type *webrtc.TrackRemote has no field or method WriteRTCP) after upgrading from v3.

Cause: v4 moved RTCP writing onto the PeerConnection. A track can only read.

Fix: keep the publisher's *webrtc.PeerConnection next to the track and call pubPC.WriteRTCP(pkts) — and rewrite the target SSRC first, because viewer feedback (PLI / FIR / NACK) references the viewer's SSRC, not the publisher's:

for _, p := range pkts {
    switch pkt := p.(type) {
    case *rtcp.PictureLossIndication: pkt.MediaSSRC = uint32(t.remote.SSRC())
    case *rtcp.FullIntraRequest:      pkt.MediaSSRC = uint32(t.remote.SSRC())
    case *rtcp.TransportLayerNack:    pkt.MediaSSRC = uint32(t.remote.SSRC())
    }
}

Get that SSRC rewrite wrong and you get the worst kind of bug: RTCP flows, nothing errors, and the publisher just never sends you a keyframe.

2. `event.streams` is empty in `ontrack`

Symptom: the viewer's peer connection reports inbound-rtp bytes and a resolution, ICE is connected, getStats() looks perfect — and the video element stays black.

Cause: video.srcObject = e.streams[0] where e.streams is an empty array assigns undefined. Nothing throws. It looks like a media failure and it is a UI bug.

Fix: fall back to a stream built from the track itself:

p.ontrack = (e) => {
  const ms = (e.streams && e.streams[0]) || new MediaStream([e.track]);
  video.srcObject = ms;
};

This one is nasty precisely because the statistics are good. Every number says the stream is arriving. Only video.srcObject knows the truth, and nothing queries it.

3. Stale JavaScript after every edit

Symptom: you change viewer.js, reload, and the old behaviour is still there. Hard reload fixes it. Then it comes back.

Cause: http.FileServer sends Last-Modified but no Cache-Control, so the browser applies heuristic caching and serves the script from memory.

Fix: wrap the static handler and send Cache-Control: no-cache so the browser always revalidates. Cheap — 304s carry no body.

The reason this is worth its own entry: it makes you doubt your own fixes. You "verify" a change, see the old behaviour, and go looking for a bug that is not there.

4. Forwarding RTP without rewriting payload types

Symptom: the viewer's SDP negotiates fine, but Chrome drops every packet or shows a black frame, and the server logs a codec the viewer never agreed to.

Cause: the server's default MediaEngine has its own payload-type table. If the publisher sends VP8 on PT 96 and the viewer side re-offers it as PT 100, the RTP you forward blindly is garbage for the viewer — the payload type is a number, and the number is per-connection.

Fix: build the viewer-side PeerConnection from a MediaEngine that registers the publisher's own codec parameters, including its payload type:

me := &webrtc.MediaEngine{}
for _, t := range tracks {
    me.RegisterCodec(t.remote.Codec(), t.remote.Kind())
}
api := webrtc.NewAPI(webrtc.WithMediaEngine(me))

Then track which codecs that PC was built for. If the publisher adds a codec the PC does not know, rebuild the PC rather than trying to renegotiate it in place. Trying to be clever here is how you get an intermittent bug that only shows up when someone publishes screen share after camera.

5. ICE candidates that arrive before the remote description

Symptom: AddICECandidate: InvalidStateError, and connections that only come up on the second try.

Cause: onicecandidate on the client fires before its SDP has reached the server, so trickled candidates land while the server still has no remote description to attach them to.

Fix: buffer candidates per client until SetRemoteDescription has been applied, then flush them. It is about fifteen lines and it removes an entire class of "sometimes it doesn't connect".

6. Republishing stacks state

Symptom: after the publisher's connection fails and it republishes, viewers see two video tracks — or the picture only updates every other attempt.

Cause: the publisher's websocket survived, so the server kept its old PeerConnection, its old track list and its old viewer senders, and merged the new session into them. From the server's point of view this is not a new publisher at all.

Fix: if a second offer arrives on a session whose remote description is already set, treat it as a republish. Close the server-side PC, clear the room's tracks, tear down every viewer PC, broadcast publisher{live:false}, then negotiate from scratch. Viewers must also drop their PeerConnection on live:false — otherwise they hold a dead one and autoplay silently stops.

This is the bug that taught me the difference between "the socket is alive" and "the session is alive". They are not the same thing.

7. A backgrounded tab stops the source

Symptom: the self-test page reports running… forever — no frames, no bitrate — but only when you switch to another tab. Coming back "fixes" it.

Cause: the canvas source was drawn from requestAnimationFrame, which browsers stop entirely for hidden documents. No drawing means captureStream() has no frames to emit, so the publisher sends nothing. It looks like a media failure. It is not one.

Fix: drive the source from a timer (setInterval) instead of rAF, and decide pass/fail from framesDecoded in getStats() rather than from requestVideoFrameCallback — which is also rendering-dependent. A backgrounded tab paints nothing but still decodes.

This one is worth internalising beyond the test page: a publisher's tab is usually backgrounded. Anything you build on rAF will stop working the moment your user switches to another window, which is exactly when they are streaming.

8. Renegotiating once per track

Symptom: viewers receive one offer per track when a publisher starts audio + video, and browsers answer them out of order.

Cause: OnTrack fires once per track. Negotiating inline races.

Fix: debounce. One time.AfterFunc(250ms) per room, cancelled and restarted on each new track, that renegotiates every viewer once. Serialize viewer-side SDP handling in the browser with a promise chain too, or the same race reappears on the other end.

9. Reverse proxies drop the idle signaling socket

Symptom: everything works locally, but behind Cloudflare or nginx a long session suddenly reconnects — or a publisher's socket dies mid-stream and comes back as a second publisher (see #6).

Cause: signaling is a flurry of messages at connect time and then goes completely silent for as long as media flows. Reverse proxies close idle WebSockets on a timer — Cloudflare around 100s, nginx's proxy_read_timeout 60s by default. Nothing is wrong with the media path. The signaling socket just gets reaped.

Fix: let the server generate the traffic, and require a pong. The instinct is a JS setInterval heartbeat on the client, but browsers cannot send protocol-level ping frames from JS, and timers get throttled in a background tab — which is exactly where a publisher's tab sits:

// writeLoop
ticker := time.NewTicker(25 * time.Second)
c.conn.WriteControl(websocket.PingMessage, nil, time.Now().Add(10*time.Second))

// readLoop
_ = c.conn.SetReadDeadline(time.Now().Add(60 * time.Second))
c.conn.SetPongHandler(func(string) error {
    return c.conn.SetReadDeadline(time.Now().Add(60 * time.Second))
})

Protocol pings are answered by the browser itself, so this works even in a hidden tab.

It also buys you liveness detection for free: a peer that stops ponging is dropped within 60s and releases the room, instead of leaving it stuck on "room busy" after someone closes their laptop. A reconnecting publisher then looks like a second publisher — which is what #6 defends against. That is not a coincidence; that is the actual sequence of bugs you hit, in order.

The pattern worth taking away

Five of the nine present as "the video is broken". Two of those are not media bugs at all (#2 is a UI assignment, #7 is rAF being paused). The rest are lifecycle bugs: a socket that outlives its session, a candidate that arrives before the description it belongs to, a payload type that means different things on different connections.

WebRTC gives you excellent statistics and no error messages. So the instinct is to go straight to getStats() — and it will happily tell you that everything is fine while the user stares at a black rectangle. Check the boring layer first. Is srcObject set? Is the tab visible? Did the socket get reaped? Those three questions would have saved me most of the time these nine bugs cost.

The kit

I put the result of all this into a starter kit — the signaling server and SFU (Go, Pion v4), the browser publisher and viewer, the auto-reconnect chain, the diagnostics panel, the deploy files for systemd / Caddy / Docker and the no-domain-tunnel route, plus the full pitfalls doc with symptom → cause → fix for each entry above.

There is a live demo you can open without an account, and a canvas self-test page that exercises the whole path and needs no camera: https://lowlatencykit.com

It is paid (early access, Basic $99 / Pro $199 / Team $499, with an early-bird code on the landing page). The pitfalls above are free, and always will be — that part is not a teaser, it is the actual content.

DEV Community: AiLaoHuYu

What breaks when you self-host a TURN server (coturn — symptom, cause, fix)

First: is TURN even your problem?

It says it started and is bound to nothing

The relay address points inward

You opened the control port and called it done

Nobody can authenticate, and only the log will say why

The certificate is valid and coturn still cannot read it

The blocklist is doing exactly what it was designed to do

It works until it does not: quotas, TTLs and the bill

The order I would check these in

The kit

WebRTC works on your laptop. Here is what breaks when you put it on a server.

The split that explains most "it connects but there's no video"

Trap 1: your ICE candidates are lies

Trap 2: the firewall that has nothing to do with your app

Trap 3: your reverse proxy reaps the idle socket

The order I would do this in from scratch

The kit

What actually breaks when you build a WebRTC SFU in Go

1. TrackRemote.WriteRTCP is gone in Pion v4

2. event.streams is empty in ontrack

3. Stale JavaScript after every edit

4. Forwarding RTP without rewriting payload types

5. ICE candidates that arrive before the remote description

6. Republishing stacks state

7. A backgrounded tab stops the source

8. Renegotiating once per track

9. Reverse proxies drop the idle signaling socket

The pattern worth taking away

The kit

1. `TrackRemote.WriteRTCP` is gone in Pion v4

2. `event.streams` is empty in `ontrack`