Troubleshooting

Installation Health Check (Doctor)

If you encounter issues during or after installation, run the diagnostic script from your install directory:

# From your install directory (default ~/fluxomni)
./doctor.sh

The script verifies:

• Docker and Docker Compose installation
• Environment configuration (.env)
• Port availability (checks for conflicts with other services)
• Container running status
• Disk space and data directory integrity

Container Does Not Start

Navigate to your Fluxomni Studio install directory and check the logs:

# Default: ~/fluxomni
cd ~/fluxomni
docker compose logs -f frontend control-plane media-node

For standalone remote media-node installs:

# Default: ~/fluxomni-media-node
cd ~/fluxomni-media-node
docker compose logs -f media-node

Common causes:

• Docker daemon is not running.
• The selected image tag does not exist.
• FLUXOMNI_CONTROL_PLANE_INTERNAL_AUTH_TOKEN is missing from .env after a manual install.
• The configured frontend HTTP port, 1935, 8000/tcp, 8003/tcp, 8000/udp, 8081/tcp (loopback), 10080/udp, 50051/tcp, or 50052/tcp is already in use.
• For standalone media-node installs, the control-plane RPC endpoint in .env is unreachable from the media server.
• For standalone media-node installs, the advertised FLUXOMNI_MEDIA_NODE_ENDPOINT does not point back to the media server.

Media Node Does Not Appear in Fleet

If the control surface loads but a standalone node never shows up under /fleet, check the media-node logs:

cd ~/fluxomni-media-node
docker compose logs -f media-node

Look for a successful Registered media node with control plane message. If it never appears, verify:

• FLUXOMNI_CONTROL_PLANE_RPC_ENDPOINT is reachable from the media-node host.
• FLUXOMNI_CONTROL_PLANE_INTERNAL_AUTH_TOKEN matches the control-plane value exactly.
• FLUXOMNI_MEDIA_NODE_PUBLIC_HOST and FLUXOMNI_MEDIA_NODE_ENDPOINT point back to the actual media-node host and published gRPC port.
• Any firewall between hosts allows TCP 50052 to the control-plane and the published media-node gRPC port back to the node when remote operators or services need it.

SRS Reports Too Few Open Files

1128 exceed max open files=1024 means the container’s file limit is below SRS’s startup requirement.

Rerun the latest installer with your existing directory and explicit capacity maintenance mode. It supplies limits of 65,536, including for v26.3.2 assets. Container recreation interrupts active streams but retains mounted data.

For manual installs, add this under media-node and check for conflicting overrides:

    ulimits:
      nofile:
        soft: 65536
        hard: 65536

Apply the change through Capacity Ledger Upgrades, then verify:

docker compose exec media-node sh -c 'ulimit -Sn; ulimit -Hn'

Both values should be 65536. Applying the change requires container recreation, not a restart.

Generated URLs Use the Wrong Hostname or IP

If the UI shows RTMP, HLS, SRT, or WebRTC URLs with a private IP, Docker hostname, or old domain, update these values in .env and restart the stack:

• FLUXOMNI_PUBLIC_HOST for control-plane links
• FLUXOMNI_MEDIA_NODE_PUBLIC_HOST for media ingest and playback links

On current releases, /routes is the main operator surface and /fleet shows attached media nodes. Those pages use the configured public hosts when they render copyable endpoints.

Check Running State

From your install directory:

docker compose ps

Clean Restart

Use Capacity Ledger Upgrades for a planned restart. Disable and drain routes while the old reporters are alive; restarting containers does not clear old reservations.

Playlist File Errors

Files in a route playlist show a signal integrity badge:

• REF — the file matches the reference stream parameters. No issues.
• DIFF — the file has different codec, resolution, or frame rate than the reference. This may cause brief glitches or quality changes during playback transitions.
• ERROR — the file could not be probed. It may be corrupt, still downloading, or in an unsupported format.

To fix DIFF warnings, re-encode files to match the reference parameters shown in the playlist status bar (codec, resolution, frame rate, audio channels).

Disk Space

If the control-plane or media-node containers exit unexpectedly, check available disk space:

df -h ~/fluxomni/data

Playlist file downloads and DVR recordings can fill the disk. Free space by:

• Clearing unused playlist files from route playlists.
• Removing old DVR segments from data/dvr/.
• Moving the data directory to a larger volume and updating FLUXOMNI_CONTROL_PLANE_DATA_DIR and FLUXOMNI_MEDIA_NODE_DATA_DIR in .env.

Port Already in Use

If Docker fails with an error like:

failed to bind port 0.0.0.0:80/tcp: Error starting userland proxy: listen tcp4 0.0.0.0:80: bind: address already in use

Another service on the host is already listening on that port. This is common on NAS devices (Synology, QNAP, Unraid) where the built-in web UI occupies port 80. Port 8000 (HLS TCP / RTC UDP) is another frequent conflict — Synology DSM uses it as an alternative HTTP port, and media apps like Plex or Jellyfin may also bind to it.

Fix: override the conflicting host ports in .env without editing docker-compose.yml:

# Change the Control Surface port from 80 to 8080
echo 'FLUXOMNI_FRONTEND_HTTP_PORT=8080' >> .env

# Change HLS TCP port from 8000 to 8800 (if 8000 is also taken)
echo 'FLUXOMNI_MEDIA_NODE_HLS_PORT=8800' >> .env

# Change WebRTC media UDP and WHIP signaling TCP independently
echo 'FLUXOMNI_SRS_RTC_PORT=8800' >> .env
echo 'FLUXOMNI_MEDIA_NODE_WHIP_PORT=8803' >> .env

Apply the changes using Capacity Ledger Upgrades. For an already running installation, drain routes before recreating containers.

Access the Control Surface at http://<HOST-IP>:8080. If you also set FLUXOMNI_PUBLIC_URL, make sure it includes the new port (e.g. http://nas.local:8080).

Multi-Subnet and NAT Environments

In environments with multiple networks (e.g. cloud VPCs, complex office LANs, or behind NAT), the Web UI might be unreachable if the public-facing address is misconfigured.

The Self-Host Doctor (./doctor.sh) will automatically detect your local IP addresses and warn you if FLUXOMNI_PUBLIC_HOST is set to a restricted loopback address.

Symptoms:

• Browser shows “Connection Timed Out” or “Connection Refused”.
• The doctor script warns that FLUXOMNI_PUBLIC_HOST does not match any local IP.

Resolution:

1. Run the Doctor: ./doctor.sh to see the recommended IPs for your host.
2. Set the correct Public Host: ensure FLUXOMNI_PUBLIC_HOST in .env is set to the IP or hostname that your browser uses to reach the server.
3. Bind to all interfaces: if you want the Control Plane to be reachable from any network connected to the server, ensure FLUXOMNI_CONTROL_PLANE_HTTP_BIND is set to 0.0.0.0:<port> (default in most setups).
4. Check NAT Reflection: if you are accessing the server via a public IP from inside the same LAN, ensure your router supports NAT reflection (Hairpin NAT).

If you are using a reverse proxy (Nginx, Traefik, Caddy), set FLUXOMNI_PUBLIC_URL to the full proxy URL:

FLUXOMNI_PUBLIC_URL=https://fluxomni.example.com

All port mappings in docker-compose.yml support the same pattern — override via the corresponding FLUXOMNI_* variable in .env:

Firewall and Port Issues

Fluxomni Studio uses both TCP and UDP ports. A common mistake is only opening TCP:

SRT (port 10080) is UDP only. If SRT publishers cannot connect, verify that UDP traffic is allowed through your firewall or cloud security group.

WHIP needs both signaling TCP and media UDP: by default TCP 8003 and UDP 8000. HLS uses TCP 8000 separately. If you override ports, open the matching firewall/cloud rules; changing the HLS port does not change the RTC UDP listener.

Stream Quality Issues

If the output stream has artifacts, stuttering, or audio sync problems:

• Check the Signal Integrity panel on the routes list for mismatch or fetch warnings.
• Open the route workspace and verify the input codec info matches what your encoder is sending.
• Ensure your encoder bitrate does not exceed the server’s upload bandwidth.
• For playlist playback, verify all files use the same codec, resolution, and frame rate as the primary source.

Cannot Sign In

If you are locked out of the Control Surface:

• Verify the username and password. Passwords are case-sensitive.
• If you forgot the admin password, current installs store user accounts in data/state.db, not data/state.json. Stop the stack first, back up data/, and use sqlite3 data/state.db as a last-resort recovery path if you need to inspect or repair the users table before restarting.
• If no user accounts exist, Fluxomni Studio falls back to the open admin shell. After emergency recovery, use Settings to create a new admin account before re-enabling named-user sign-in.

Rollback to a Previous Version

Retain the database and diagnose the candidate using Capacity Ledger Upgrades. A predecessor image may not understand migrated state or durable capacity ownership; changing the image tag and recreating containers is not a verified rollback.

Restoring an older database and matching images requires a separately reviewed recovery procedure, backups and proof that all predecessor execution is stopped. Never erase the ledger or reuse the initialization acknowledgement to release exposed ownership. Available image tags are listed on GitHub Releases.