Troubleshooting and FAQ

Troubleshooting and FAQ

Common problems and how to resolve them. If something here doesn't match the running code, the binary wins — check /api/docs and the changelog.

Credentials

I lost the first-run passwords. They're stored as bcrypt hashes, so they can't be recovered. Reset the admin user from the admin UI (if you can still log in), or — as a last resort — stop the server, remove the admin user block from tinyice.json, and let it regenerate on next start. Source/mount passwords can be reset per mount in Admin → Streams → Edit.

Where did systemd put the generated password?

sudo journalctl -u tinyice | grep -A4 "FIRST RUN"

Streaming in

An encoder connects then immediately drops. Wrong source password (check the per-mount password vs default_source_password), the mount is in disabled_mounts, or you hit max_listeners. Watch the log at -log-level debug.

OBS won't publish over RTMP. RTMP is off by default — set ingest.rtmp_enabled: true and a port, then reload. Server = rtmp://<host>/<mount>, Stream Key = the mount's source password. See Streaming Sources.

SRT input has glitches / no video. Confirm the stream is MPEG-TS with both audio and video, raise srt_latency, and check the path isn't dropping UDP. The demuxer resyncs on misaligned input, but a lossy path still shows up as artifacts.

A source vanished after a couple of minutes. Silent mounts (no data ~2 min) are auto-removed by the health monitor. If the encoder stalled, that's expected. Transcoded outputs are exempt and survive source flaps (Transcoding).

Playback out

Browser shows "0 listeners" while people are watching video. Older behaviour. Current builds count browser viewers via a 30 s sliding-window IP tracker and render "viewers" for video. Update if you see this.

WebRTC (?webrtc=1) playback is black or fails. WHEP currently needs the encoder to publish without B-frames (x264 bf=0, or Profile baseline). Use HLS otherwise — it's the default, robust path. See Playback and Output.

HLS latency is higher than expected. Default segments are 1 s, keyframe-aligned. Set the encoder keyframe interval to 1 s. If you're behind a proxy, make sure it isn't buffering responses (see below).

Stream stutters / underruns shortly after connecting. Usually a too-small burst buffer for the bitrate. Raise the per-mount burst size in Admin → Streams → Edit (default 512 KB).

TLS / proxy

Do I need nginx/Caddy in front? No. TinyIce terminates TLS itself with built-in ACME and serves large numbers of connections directly — running it on 80/443 is a first-class, supported setup. A reverse proxy is optional. See Deployment.

ACME certificate isn't issued. Ports 80 and 443 must be publicly reachable for the challenge, domains must resolve to this host, and the process must be able to bind those ports (setcap cap_net_bind_service or run packaged). Check the log for the ACME error.

Behind a proxy, bans don't work / every client looks like 127.0.0.1. Set trusted_proxies to the proxy's address so X-Forwarded-For is honoured — and remember that makes loopback no longer auto-whitelisted. See Security. Also disable proxy response buffering on the stream/HLS/SSE paths.

Operations

The server hung / is unresponsive. Capture profiles from the internal metrics port (firewall it; default :8081):

curl -o goroutines.txt 'http://HOST:8081/debug/pprof/goroutine?debug=2'
curl -o mutex.txt      'http://HOST:8081/debug/pprof/mutex?debug=2'

File an issue with those attached. Several past hangs (a buffer-scan infinite loop, lock contention, goroutine leaks) were fixed this way — make sure you're on a current release first.

Memory climbs over days of uptime. Past goroutine leaks in the transcoder retry loop are fixed in 2.6.0+. If you see it on a current build, capture a heap profile (/debug/pprof/heap) and report it.

Can I run multiple stations? Yes — multiple mounts, multiple AutoDJ instances, multiple transcoders and relays on one node. Cross-node shared state isn't supported; relay chaining is. See Architecture.

How do I update without dropping listeners? Hot-swap the binary (SO_REUSEPORT) or reload config with SIGHUP. See Command Line and Signals.

Still stuck?

• Interactive API reference on your instance: /api/docs.
• Search or open an issue.
• Security-sensitive? Use private disclosure, not a public issue.