Troubleshooting

Find what you're seeing below and work through the fix. Most of these show up as a toast in the bottom of the screen, or as a status chip near the Stream/Record controls.

#"KERYX hit an error" (the control window went blank)

If the KERYX window suddenly shows KERYX hit an error with some technical text, the controls stopped but the projector, stage display, stream, and recording keep running.

1. Click Reload KERYX (or press Cmd+R). The controls come back on the same service.
2. Click Copy error and send it to support so it gets fixed. The error is also saved to KERYX's log.

#Announcements deck won't update

Click Refresh now under Settings → Slides & Bibles → Announcements. If it fails, the message says what to do:

• Share it with <email> — open the deck in Google Slides, click Share, and add that Google account. Or set it to "Anyone with the link can view".
• Reconnect Google to allow reading Slides — go to Settings → Publishing and click Reconnect, then sign in as the church account.
• Connect the church Google account — no Google account is connected yet. See Settings → Publishing.

#"mic permission needed"

The audio level meter shows this when macOS has denied KERYX access to the microphone. Open System Settings → Privacy & Security → Microphone and turn KERYX on, then relaunch KERYX. See Resetting camera/mic permissions below.

#No audio devices found

Settings → Audio & Camera shows "No audio devices found. Plug in the mixer and press refresh" when KERYX can't see any audio interface. Plug in your mixer/interface (a StudioLive, a USB interface, etc.), then press the refresh button next to the Device dropdown. If it still doesn't show up, check the interface is powered on and its USB/network connection is good, and that no other app has it exclusively locked.

The meter itself shows no input when it can start listening but finds no signal — check the interface is selected under Settings → Audio & Camera → Device and the correct Channels pair is chosen.

#Camera preview won't start

A toast reading "Could not start the camera preview" (or the raw error from the pipeline, when there is one) means the camera couldn't be opened. Check:

1. Settings → Audio & Camera → Camera → Device is set to the camera you're using, and its Resolution is one the camera actually supports.
2. macOS camera permission hasn't been denied — see Resetting camera/mic permissions below.
3. The camera isn't already open in another app (Zoom, Photo Booth, OBS, etc.) — only one app can use most cameras at a time.

#Stream error / stuck Reconnecting

"Stream error — check Settings" next to the stream controls means the last stream attempt failed outright — check Settings → Streaming: server URL, stream key, and that your internet connection is up.

Reconnecting (amber, pulsing) means the stream dropped mid-broadcast and KERYX is trying to re-establish it — this is often a brief network hiccup and recovers on its own. If it stays in Reconnecting for a long time, check your internet connection; you can also stop and restart the stream from the stream controls.

If starting the stream fails immediately, you'll see a toast: "Could not start the stream. Check Settings → Streaming."

#Recording won't start

A toast reading "Could not start recording. Check Settings → Recording" means the recorder couldn't start — check Settings → Recording (output folder exists and is writable, resolution/encoder are valid for this Mac) and Settings → Audio & Camera (a camera and audio device are actually selected).

If recording was running and the button flips back to Start Recording mid-service, the recorder stopped unexpectedly — click Start Recording again. Whatever was captured up to that point is still on disk; open it from Recordings.

#Uploads failing (podcast / YouTube)

On the Recordings or Trim screen, a job that reads:

• Needs attention — <reason> is stuck on something only a person can fix — most often YouTube isn't connected yet (Settings → Publishing → Connect), YouTube access was revoked (Reconnect), R2 storage isn't configured, or a re-upload needs confirming. Fix the underlying issue, then press Retry.
• Failed — <reason> means KERYX retried automatically (up to 8 attempts, backing off further each time) and it still didn't go through — usually a persistent network or account problem. Fix it, then press Retry.

See Publishing for the full list of job states and what each one means.

#A recording says "file missing"

This means KERYX's database still has a record of the session, but the file at that path isn't there anymore — it may have been moved, deleted, or is on a drive/network location that isn't currently connected. Reconnect the drive if that's the cause, or use Show in Finder to check the exact path KERYX expects. Trim & publish is disabled until the file is found.

#Sync problems

#Cloud shows "unreachable" or "sync failed"

Settings → Accounts → KERYX Cloud shows the sync health under your signed-in email:

• Cloud unreachable since <time> — retrying in N min means KERYX can't reach the cloud (usually a network problem on this Mac or an outage). It backs off automatically (2 minutes, doubling up to every 30 minutes) and keeps retrying — no action needed unless it persists for a long time, in which case check this Mac's internet connection.
• Sync failed (no automatic retry noted) is a different kind of error — often a rejected write. Note the detail shown underneath; if it persists, whoever manages KERYX for your church may need to look at it.

#Sign-in code isn't arriving

1. Check spam/junk — the code comes from KERYX Cloud's email sender and junk filters sometimes catch it.
2. Codes expire after 1 hour — if it's been a while, request a new one.
3. Only email addresses that already have a KERYX Cloud account can sign in this way; a brand-new email won't receive a code. Ask whoever manages your church's KERYX Cloud account to add you first.

#Update banner not appearing

The update banner needs this Mac to be signed in to KERYX Cloud (Settings → Accounts) — the update feed is authenticated, so with nobody signed in KERYX has no way to check. It also only checks every 4 hours (starting shortly after launch), so a just-published update may take a little while to show up. The header always shows the version this Mac is actually running (see below) — compare that against what you expect to confirm whether an update is really pending.

#Resetting camera/mic permissions

If KERYX never prompted you for camera/microphone access, or you accidentally denied it, macOS won't ask again on its own:

1. Open System Settings → Privacy & Security → Camera (and separately Microphone).
2. Find KERYX in the list and turn it on. If it isn't listed at all, quit and relaunch KERYX so macOS prompts again.
3. Relaunch KERYX.

#Still stuck?

Check the KERYX version this Mac is running — it's shown in the header as v0.4.2 (yours may differ) — and contact whoever set up KERYX at your church with that version number and what you saw.