▶Stream4US

Troubleshooting

Something does not work: find the symptom, then the cause and the fix.

Find the symptom, then try the causes in order. Most problems are solved in the first two lines of each section. If nothing helps, write down what you see (the exact message, the time, the page address) and contact your administrator.

Streaming (sending video)

The Overview page stays "Offline"

  1. Wrong address or key. Copy both with the Copy buttons on the Overview page and paste them into the encoder. No spaces before or after. In OBS the server is the rtmp://.../live address and the key goes in "Stream Key".
  2. A red message in the Stream box tells you what the server saw: a wrong key, a suspended account, or a blocked address.
  3. SRT: the church firewall must allow outgoing UDP to port 9000. Many guest Wi-Fi networks block it; try RTMP to check.
  4. RTMP: outgoing TCP port 1935 must be open. Some networks allow only web ports; then use SRT, or ask your administrator.
  5. "Access from your address is blocked": too many wrong keys or passwords from your network. It clears by itself after an hour; your administrator can remove it at once (Admin → Blocking).
  6. Account paused: the trial ended or the account was suspended. The dashboard shows the reason.

It goes live, then drops every few minutes

  1. Upload too slow for the bitrate. Test at speedtest.net: the upload must be at least 1.5 times your total bitrate. Lower the bitrate (2,500 kbps for 720p is safe).
  2. Wi-Fi: use a network cable for the streaming computer.
  3. Use SRT instead of RTMP: it survives short drops and lost packets.
  4. Computer too busy: in OBS look at "dropped frames due to encoding lag"; choose a faster encoder preset or your graphics card.
  5. Recordings are not split by short drops: when the encoder returns within 90 seconds, the same recording continues.

Viewers see buffering, or the picture freezes

  1. Same causes as above: the stream that reaches the server is not smooth. The Overview page shows the bitrate: it should be steady.
  2. Keyframe interval must be 2 seconds (OBS: Output → Keyframe Interval 2).
  3. Viewers on slow internet: send several qualities (see Help → Several qualities) or ask for a plan with server-made qualities.
  4. One viewer only: it is their connection; the player lowers the quality by itself when it can.

No sound, or sound out of sync

  1. The encoder must send AAC audio (OBS does by default). Check that the mixer output is not muted and the meter moves.
  2. In the desktop sender, pick the right microphone and watch the sound meter.
  3. Out of sync: set the sample rate to 48 kHz in the encoder and the mixer; avoid "variable frame rate" sources.

The delay is long

A delay of 10 to 20 seconds is normal for internet streaming to many devices. To reduce it: keyframe interval 2 seconds, and ask the administrator for a shorter segment length (Admin → Settings). Viewers who paused or rewound are behind on purpose; Back to live under the player catches up.

"Go live" in the browser cannot use the camera

  1. The address must start with https://. Over plain http browsers refuse the camera.
  2. Allow the camera and microphone when the browser asks. If you refused once, click the lock icon in the address bar and allow them.
  3. On a Mac: System Settings → Privacy & Security → Camera and Microphone, allow your browser.
  4. Close other programs that use the camera (Zoom, Teams, OBS).

The desktop sender does not connect

  1. Check the pairing code on the Overview page and the site address you typed.
  2. The sender uses SRT (UDP 9000): see the firewall note above.
  3. ffmpeg: the Windows and Mac zips include it (keep it next to the program); on Linux sudo apt install ffmpeg. A Mac with only the included ffmpeg sends RTMP: the church firewall must let TCP 1935 out (SRT needs UDP 9000).
  4. A Mac refuses to open it: right-click → Open → Open the first time, or System Settings → Privacy & Security → Open Anyway. Windows "protected your PC": More info → Run anyway.
  5. The log is encoder.log in the settings folder (Windows %AppData%\castgate-encoder, Mac ~/Library/Application Support/castgate-encoder, Linux ~/.config/castgate-encoder).

First thing to try

Stop the service and run the check with the same flags it uses; it names what is wrong and how to fix it:

sudo systemctl stop castgate sudo castgate -preflight -data /var/lib/castgate -domain live.example.com sudo systemctl start castgate

On an edge server add -edge https://main-server to the check.

To watch everything the server does while you reproduce a problem, run the installed service in your terminal (Ctrl+C stops it): sudo systemctl stop castgate && sudo bash deploy/run-foreground.sh --service, then sudo systemctl start castgate afterwards (docs/TESTING.md).

An edge server shows errors or is missing in Admin → System

  1. "The streaming server cannot be reached": the edge cannot reach the -edge address. Check it from the edge: curl -I https://live.example.com/.
  2. Not listed in Admin → System: add the edge's address to the main server's -trusted-proxies and restart it. Until then viewers watching through it all appear at the edge's address and location.
  3. Low share "from its memory": normal right after a start, and for channels with very few viewers.
  4. "Runs version X": update the edge to the main server's version.

Recording storage (S3)

  1. "Test storage" says Check the access key and secret: the key or secret is wrong, or the key may not use this bucket. Create the bucket first: the bucket does not exist, or "bucket name in the path" is set wrongly (on for MinIO and Ceph, off for Amazon S3). Check the region: Amazon needs the bucket's region.
  2. Admin → System says recordings could not be copied: the last error is shown there; the copy is tried again every minute.
  3. Removed recordings do not play with "straight from the bucket": allow GET from any origin in the bucket's CORS settings, or turn that option off (they then come through this server).

No Chromecast or AirPlay button on the player

The buttons appear while something plays, only in Chrome or Edge (Chromecast) and Safari (AirPlay), and only when a TV of that kind is on the same Wi-Fi network. Some company and school networks block casting.

The phone sender does not work

  1. "The camera only works on secure pages": the site must use https:// (-domain).
  2. Camera not allowed: iPhone → Settings → Safari (or the app) → Camera and Microphone → Allow; Android → tap the lock by the address → Permissions (in the Sender app: Android Settings → Apps → castgate Sender → Permissions).
  3. "This browser cannot send video": iPhone needs iOS 14.5 or newer and Safari; Android needs Chrome or the app.
  4. "The connection is too slow for this quality": choose 480p, move closer to Wi-Fi.
  5. It stopped when the screen turned off: keep the sender on screen and the phone plugged in.
  6. "No longer paired": the phone was removed on Overview; create a new pairing code.

The desktop encoder picks a low picture size or frame rate

The log (encoder.log) says which format it chose: camera "...": N formats, using 1280x720 at 30 fps mjpeg. The encoder takes the camera's formats as offered; a webcam that offers 720p only at 10 fps on its plain format is opened in MJPEG. Choose another quality, or another camera or capture card, if the list has nothing better.

There is no encoder download on the Overview page

The packages are not on the server yet. They are put in place by themselves when the server program runs from the release folder (next to dist/encoder/); otherwise copy them once: cp dist/encoder/* <data>/downloads/ (see README → Desktop encoder). Admin → System → "Desktop encoder downloads" lists what is there and what is missing. Until then use OBS, vMix or a hardware encoder with the SRT address (Help → Set up SRT in other encoders).

Watching

"Viewer limit reached" (or "This stream is full")

The channel has as many viewers at once as its plan allows. Others can join when someone leaves. The owner sees the limit on the Audience page; a larger plan raises it. Every way of watching counts: web, TV apps, VLC links and radio listeners.

The page says "Offline" but we are live

  1. Reload the page. If it stays offline, check the Overview page: is the stream really arriving?
  2. A private event is running: the page asks for the access code.
  3. Who may watch: the viewer's address, country, network or city is not allowed (Settings → Who may watch). The page then shows your refusal message instead of the player.

The video does not play at all

  1. Try another browser or a phone. Very old browsers (Internet Explorer, old Smart TV browsers) cannot play it; use the TV apps.
  2. Company or school networks sometimes block video; try mobile data.
  3. A link copied from an app (HLS address) needs the playback key in it; copy it again from the recording's Links.

"Not available in your area" for someone who should watch

  1. Settings → Check an address with the viewer's address (they can find it by searching "what is my IP"). It says where the address is placed and which rule refused it.
  2. Locations are approximate: providers often appear in their nearest big city, and VPNs and company networks appear where their exit is. Prefer countries or networks over cities for small towns.
  3. A block always wins over an allow. The administrator may also block places for the whole server; the check shows "server-wide" then.

Peer-to-peer: "from other viewers" stays at 0%

  1. Two or more viewers must watch the same stream at the same time in Chrome, Edge, Firefox or desktop Safari. iPhones, iPads, the TV apps and outside players play from the server only.
  2. The channel switch (Settings → Peer-to-peer playback; it only appears while the server switch is on) and the server switch (Admin → Peer-to-peer → Settings → "Channels may use peer-to-peer playback") must both be on. To check from a viewer's side, add ?p2pinfo=1 to the channel page address on two devices: the readout at the bottom left says ON or OFF, the number of connected viewers and the share from viewers.
  3. Behind a reverse proxy (nginx, a CDN), WebSocket upgrades for /p2p/ws must be passed through. In nginx: proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";.
  4. Viewers on strict company or mobile networks may not reach each other directly; a TURN relay (Admin → Peer-to-peer → Built-in relay, or an outside coturn) helps them. Test STUN and TURN on that page says which entry fails. A relay that allocates but does not forward means the relay port range (49160-49360 UDP by default) is closed in the firewall. The Audience page shows how many connected and how many needed a relay.
  5. Admin → Peer-to-peer → Signaling lists joins and refusals; "join token" means the page was open longer than 12 hours (reload it).
  6. To find out about one network (a church's guest Wi-Fi, a mobile provider), send the Field test link from Admin → Peer-to-peer to someone on it. The report says which part fails: STUN failed, relay OK: viewers there can share through the relay; relay failed with "the relay did not answer": the relay port or the public address is wrong, or a firewall on that network blocks UDP (try the relay over TCP or TLS); signaling failed: a proxy on that network blocks WebSockets, so those viewers play from the server only.

There is none to make: 24/7 plays on your channel's own page, embed, stream link and TV apps whenever you are not live. Dashboard → 24/7 → Where viewers watch lists them.

The built-in relay does not start

Admin → Peer-to-peer shows why. Usually the port (3478) is taken by another program, for example a coturn already running: stop it, or choose another port. Ports below 1024 need the service to run with permission to use them.

Playback quality shows long start times or much waiting

Look at By internet provider: if one provider is much worse, the problem is on its network. If everyone is affected, check the stream (Overview: bitrate steady?), lower the bitrate, or add smaller qualities (Settings → qualities) so slow connections get a picture that fits.

Captions do not show

Press CC in the player and choose the language. On iPhone and Safari, captions are in the player's speech-bubble menu. Live captions appear 10 to 20 seconds after the words and only when the church turned them on and the server has a transcription service.

  • On iPhone, iPad, Safari, the Android TV and Fire TV app and Roku, live captions come from the Live captions track in the stream: pick it in the player's caption menu, or turn captions on in the TV's own settings (Accessibility → Captions on Android TV and Roku). Players start about 30 seconds behind live while live captions are on; a player that jumps to the very live edge can miss the newest captions.
  • The track appears only while live captions are switched on and the transcription server works. If captions stop (Chat page → Live captions shows the last error), the stream keeps playing without them.
  • Rewinding (DVR) does not have the caption track yet.

Recordings

A recording is missing

  1. Settings → Record: "always", "only scheduled events" or "never". With "only scheduled events", unscheduled streams are not kept.
  2. Streams shorter than about 15 seconds are not kept.
  3. Storage full: the dashboard says so. Delete old recordings or ask for more space.
  4. Server disk nearly full: new recordings pause until the administrator frees space (they are told by email).
  5. Look under Recordings for a "processing" entry: long services take a little while to appear after the stream ends.

An upload fails or stays "processing"

  1. The file must be a video or audio file (MP4, MOV, MKV, MP3...), at most 20 GB.
  2. Keep the page open until the progress bar finishes; then conversion runs on the server (a few minutes for an hour of video).
  3. "Failed" with a message: the file is damaged or uses an unusual format; export it again as MP4 (H.264 + AAC).
  4. Add from a link: the link must open the file itself, not a page. Google Drive files must be shared as "Anyone with the link". YouTube, Vimeo and Facebook pages cannot be imported.

Automatic captions or translation are not offered

The administrator must connect a transcription service (for captions) or a translation service (for chat and caption translation) under Admin → Settings.

24/7 and the weekly grid

Nothing plays when we are not live

  1. 24/7 must be on (the 24/7 page) and your plan must include it.
  2. There must be playable recordings: published ones for "all" or a category, or recordings in your playlist. Private recordings never play.
  3. After a live stream, playout waits 30 seconds before it starts again.
  4. With 24/7 off and a weekly grid, the channel plays only during the grid's blocks.

A grid block did not start

  1. Check the time zone in Settings: blocks follow it.
  2. The block's recording must be published (or a draft) and not private; the grid page marks problems in red.
  3. A live stream or a "Replay as live" event takes priority over the grid.
  4. A single-recording block plays once a week; if it was skipped, it waits until next week.
  5. With "Up next" cards on, a block that starts while a card is showing starts when the card ends (a few seconds late).

The "Up next" card does not appear, or looks wrong

  1. Dashboard → 24/7 → "Up next" cards: the box must be ticked. Cards appear before each recording, not during a live stream.
  2. Cards need ffmpeg on the server. Without it, recordings follow each other without cards (Admin → System shows whether ffmpeg was found).
  3. The card uses the logo and brand color from Settings. A new logo or color applies from the next recording; the preview on the 24/7 page shows it at once.

TV apps

  1. Settings → tick Show this channel in the castgate TV apps.
  2. Viewers can always type the exact web address name (for example grace-church), listed or not.

The universal app asks for a server

Type the server address (for example live.example.org, or an IP address with port such as 203.0.113.10:8080) and optionally the channel. Use Change server on the start screen to correct it.

The TV app shows an error or plays nothing

  1. Check the internet connection of the TV (another app, a speed test).
  2. Private events and private recordings are not playable in the apps; they point to the web page.
  3. The channel may be offline; "Watch from the start" or a recording plays meanwhile.
  4. Many TVs behind one internet address (a church building): the app request limit is high, but tell the administrator if apps show "too many requests".

The chat is not on the TV

The church must have the chat on and "Show the chat on the TV apps too" ticked (Chat page). Viewers hide or show it with * on Roku and the menu button on Fire TV and Android TV.

Sign-in and accounts

I forgot my password

On the sign-in page choose Forgot your password? and enter your email. The link works once, for one hour. No email? Look in spam; otherwise the owner (for team members) or the administrator can help. The administrator can set a new password for any login under Admin → Users; for an administrator login, castgate -reset-admin email:newpassword on the server also works.

My authenticator phone is lost

Use one of your recovery codes instead of the 6-digit code. No codes left? The administrator turns off two-step sign-in for your login (Admin → Users); then set it up again under Security.

A team member does not see our channel

They sign in with their own email and password. If they work in several channels, they choose yours in the Channel menu at the top of the dashboard.

Email (administrators)

  1. Admin → Settings → Send a test email. The message after it says what is wrong (password, port, sender address) and what to do.
  2. Gmail and Microsoft 365 need an app password, not the normal password; Microsoft 365 also needs "Authenticated SMTP" on for the mailbox.
  3. Timeout: many hosting providers block outgoing mail ports; use port 2525 (SMTP2GO, Brevo, Mailgun) or ask your provider.
  4. Messages in spam: set up SPF and DKIM for your sending domain at your mail service.

See the email setup guide.

Server (administrators)

The site does not open after installing

  1. systemctl status castgate and journalctl -u castgate -n 100: the last lines say what failed.
  2. Port already in use: another web server (nginx, Apache) holds port 80 or 443. Stop it or run castgate on other ports.
  3. Firewall: open TCP 80 and 443 (and UDP 443 for HTTP/3), TCP 1935 and UDP 9000.

No certificate (browser warning)

  1. The domain's DNS A (and AAAA) record must point to this server before the start.
  2. Port 80 must be reachable from the internet (Let's Encrypt checks through it).
  3. Too many attempts: Let's Encrypt limits retries; wait an hour after fixing DNS.
  4. A church's own domain: its DNS must point here too; certificates are made only for names castgate knows.

The server is slow or viewers buffer at busy times

  1. Admin → System: CPU, memory, disk, outgoing traffic against the link speed, connections. The setup checks give exact fixes (network buffers, open-file limits, BBR).
  2. Outgoing traffic near the link speed: add bandwidth or put a CDN in front (Admin → Settings → Streaming address).
  3. CPU high: server-made qualities, browser Go live and uploads use ffmpeg; use a graphics card or fewer server qualities.
  4. Connections refused (System page, "refused since start"): one address hit -max-conns-per-ip. If it is your CDN or proxy, add it to -trusted-proxies.

The disk is full

castgate pauses new recordings and uploads below 2 GB free and emails administrators. Delete old recordings, lower archive days in Plans, or add disk space. Settings and live streams keep working.

Viewers all show the same address or country

The server is behind a proxy or CDN that castgate does not trust. Start castgate with -trusted-proxies listing the proxy's addresses so the real viewer address is used.

Restoring settings from a backup

Stop castgate, copy backups/store-YYYY-MM-DD.json (or a downloaded backup) over store.json in the data folder, and start castgate again. Recordings are separate files and are not affected.

This guide is also in the castgate package as docs/TROUBLESHOOTING.md.