← BlogGuides7 min read

By Pritika Bakshi, Principal Video Streaming Engineer, creekX.io

On this page

Streaming server troubleshooting: a symptom-by-symptom guide

Live video fails in a small number of ways, and each has a short list of causes. Work from the symptom: where does the stream stop? Between the source and the server, inside the server, or between the server and the viewer? The commands below are for creekX on Ubuntu, but the reasoning applies to any streaming server.

Source: Is media leaving?; Server: Is media arriving?; Viewer: Is media playing?
  1. SourceIs media leaving?
  2. ServerIs media arriving?
  3. ViewerIs media playing?
Test each boundary before changing unrelated settings. Concept diagram; not a performance chart.
Home showing a live stream and a channel on air
Home showing a live stream and a channel on air. Open full screenshot.

Start here

  1. Run the server's own check. In creekX, More → Help checks the database, disk, FFmpeg, the media engine, email, the licence and channels, and suggests a fix for each failure.
  2. Read the logs. sudo creekx logs. Look for the stream's name around the time it failed.
  3. Find where it stops. If the stream shows as live in the app, the problem is on the viewer side. If it never appears, it is the source or the network in between.

The source cannot connect

OBS or an encoder says "failed to connect"

SRT connects, then drops, or never connects

An IP camera shows offline

Going live from the browser does not start

The stream is live, but viewers have problems

WebRTC: connects, then a black picture

Signalling (https) worked but media (UDP) did not arrive. Either 8189 is closed, the viewer's network blocks UDP and TCP to that port, or the server is behind NAT and advertising its private address. The cure for strict networks is a TURN relay on 443: TURN for WebRTC behind NAT.

HLS: buffering or falling behind

Delay much higher than expected

Players drift behind live when they buffer and never catch up. Check the encoder first: B-frames, a long keyframe interval and "quality" presets add delay before the server sees anything. Measured on a local network, creekX's WebRTC median is 0.49 s and LL-HLS 1.23–1.28 s (benchmarks); far above those means something upstream is buffering.

Audio out of sync, or missing

The server itself

CPU at 100%, dropped frames

Passthrough is cheap (49 recorded 1080p lives used 13% of a 4-core server); transcoding is not (about 0.6 of a core per live for a three-quality ladder). If CPU is pinned, count the streams with a ladder. Live encoders cannot catch up once they fall behind, so keep 30–40% headroom: sizing a streaming server.

Disk full

Recordings grow at about bitrate (Mbit/s) × 0.45 GB an hour. A 24/7 camera at 6 Mbit/s writes about 65 GB a day. Set a retention period or move recordings to object storage.

A platform says "not sending"

Paste the platform's stream key again: YouTube and Facebook sometimes issue new ones.

Ask for help with the right information

In creekX, More → Help → Download the report collects how the server is doing and its recent messages, with passwords, stream keys, tokens and email addresses removed. Send it with what you did and when it failed. The short checklist for every symptom is in the troubleshooting docs; how the parts fit is in the streaming server guide.

Try it. creekX Media Server installs on Ubuntu 24.04 with one command and is free for 14 days: install it, or start with the quick start.

Put this into practice

Implementation check

Collect evidence before a restart

You need: Access to the failing client and read access to server status/logs.

  1. Record the first error, exact version, time zone and whether the failure affects one or all viewers.
  2. Compare source arrival, watch-page access and moving picture as separate checks.
  3. Make one targeted change and repeat the same reproduction. Review logs locally before sharing a short redacted excerpt.

Pass when: The report identifies the first failing layer and the effect of a specific change.

If it fails: Restarting every process can erase the original symptom and interrupt otherwise healthy media.

Follow the product steps

Frequently asked questions

Why does WebRTC connect but show a black screen?

Signalling over https worked but the media did not arrive: the WebRTC media port is closed, the viewer’s network blocks UDP, or the server is behind NAT. A TURN relay fixes strict networks.

Why does my HLS stream keep buffering?

The bitrate is above the viewer’s bandwidth, the server’s port is full, or keyframes are too far apart. Offer an adaptive bitrate ladder, put a CDN in front, and set a keyframe every 2 seconds.

Follow the build