Troubleshooting

Symptom-first answers, grouped by the chapters that cover the feature involved. If a fix here says "see Chapter N," that chapter has the full explanation — this page only covers what to check when something isn't working.

Connecting (User app, Companion, and browser access)

These come first because a bad host/port is the single most common blocker on a fresh install, and it shows up in more than one place at once — if the User app can't connect, it's worth checking Companion too, and vice versa, since they're usually pointed at the same misconfigured address.

The User app won't connect to the Server

On first launch (or after 🖥 Server in the top bar, per Chapter 4), the User app's connection screen asks for a Server IP / Hostname and a Port (default 4500), then tests the connection before saving it. If the test fails, the screen shows:

Could not reach ClockBridge server at {host}:{port}

Before re-typing the address, check these in order:

1. Is the Server app actually running? It has no Dock icon or window — it lives in the menu bar only (Chapter 1). If it's not running, nothing on the network can reach it.
2. Is the port right? 4500 is the default the Server app listens on, but if that port was changed, both the User app and any browser bookmark need the new one.
3. Is the host actually reachable from this machine? The User app's own connection test is a plain HTTP request to http://{host}:{port}/api/health with a 5-second timeout — the same request a browser makes. If a browser on the same machine can't load http://{host}:{port}/setup either, this isn't a User-app problem: it's routing, a firewall, or the two machines being on different subnets/VLANs.
4. Empty host or an out-of-range port are caught before the network request even happens — "Enter a server IP address or hostname" or "Enter a valid port number (1-65535)" — so if you see one of those instead of the "Could not reach" message, the field itself is the problem, not the network.

Once a working host/port pair is saved, the User app remembers it and reconnects automatically on future launches — you shouldn't need to re-enter it unless the server's address actually changes.

The Companion module shows "Disconnected" or won't turn green

Companion's ClockBridge connection has the same two config fields as the User app — ClockBridge Host and Port (default 4500) — and the same failure mode: a wrong host/port here is the most likely cause. A few things specific to how the module behaves are worth knowing before you start changing settings:

• The module connects over a WebSocket, not a plain HTTP request, so a device that blocks WebSocket upgrades (some restrictive guest-network setups, for example) can fail here even if a browser can load the control panel fine on the same network.
• On a bad connection, Companion's connection status cycles through Connecting → Connection Failure/Disconnected, and the module retries automatically every 5 seconds — you don't need to manually re-save the config to trigger a reconnect attempt, just fix the host/port and it'll pick it up on the next retry (or trigger one immediately by re-entering the config).
• The Connected to ClockBridge feedback (Chapter 5) is the fastest way to build a "link is up" indicator on a button — it's an on/off feedback that tracks the same connection state shown in Companion's own connection list, so you don't need a separate health-check action.
• Since the module talks to the same REST/WebSocket API described in Chapter 5, anything that would block a browser from reaching http://{host}:4500 (firewall, wrong subnet, server not running) blocks Companion the same way. If the User app can reach the server but Companion can't (or vice versa), suspect something specific to that one machine — a firewall rule scoped to an app rather than a port, for instance — rather than the server itself.

Browser access works but the User app or Companion doesn't

If http://{host}:{port} loads fine in a browser but the User app or Companion still can't connect, the server itself is fine — the difference is almost always the exact host/port string. Double check for the easy mistakes: a : typed into the host field along with the port, an http:// prefix left in a field that just wants the bare hostname, or a port copied from a different tool's default (RossTalk's 7788, OSC's 9000 — see Chapter 5) instead of the control panel's own 4500.

Outputs (Chapter 2)

NDI stream doesn't appear on the network

• Confirm the NDI drivers are installed on the Server machine: either the free NDI Tools, or ProPresenter on the same computer, which runs them in the background (Chapter 2 — Server Setup).
• Confirm the NDI card is actually toggled on and Save NDI Settings was clicked — each output type is independent, and enabling BMD or Web Output doesn't turn NDI on.
• NDI discovery depends on multicast reaching the receiving machine. If the Server and the receiving NDI software are on different VLANs or subnets, or the network gear filters multicast, the stream can be enabled correctly and still never show up in another application's source list — that's a network configuration issue, not a ClockBridge setting.
• Check the NDI Stream Name field against what the receiving software is filtering for — a renamed stream still works, it just won't match an old saved source in the receiving app.

BMD DeckLink output isn't available, or the Device dropdown is empty

• On Windows, the setup page will tell you directly: if no DeckLink devices are detected, a notice reading "No DeckLink devices found. If you have Blackmagic hardware connected, make sure Desktop Video is installed." appears under the BMD card. This is expected on a fresh Windows install — Blackmagic's driver license doesn't allow ClockBridge to bundle DeckLinkAPI.dll, so Desktop Video has to be installed separately on that machine before any DeckLink or UltraStudio hardware will show up.
• The Format dropdown for BMD lists more frame rates than NDI's does (including 1080p 2398, which is 23.98fps rendered without the leading "23." — that's a label-formatting quirk, not a sign anything is misconfigured).
• If a previously-selected device disappears from the list — unplugged, or the machine rebooted without it connected — it still shows in the dropdown, suffixed (not detected), rather than silently reverting to "no device." Reselect it once it's physically reconnected.

Web Output page is blank, or shows the wrong thing in OBS

• The Output URL field only appears once Web Output is toggled on and saved — if it's not there, the card itself isn't enabled yet.
• For an OBS Browser Source specifically, append ?transparent=true to the copied URL, per the note on the card — without it, the output renders its normal (non-transparent) background, which will show as a solid black or colored box over your OBS scene instead of just the clock text.
• The Web Output page renders the same 1920×1080 composited canvas as NDI/BMD. If nothing has been positioned in any Clock Window (Chapter 2), the page will load successfully but show nothing on it — that's a Clock Window assignment problem (Chapter 4: assign a timer to a window), not a broken output.

External Sources (Chapter 3)

A connection's status dot is red or gray, and never turns green

Per-type setup notes on the Add-connection form (Chapter 3) exist because the most common cause of a red/gray status dot is that the corresponding setting wasn't enabled on the other application yet — the connection itself is configured correctly, but the source software hasn't opened its side. Before assuming ClockBridge is at fault, check the specific requirement for that type:

• ProPresenter — Network must be enabled in ProPresenter's own Preferences → Network.
• QLab — Workspace Settings → OSC → Use OSC Controls must be on, and the port there has to match what's entered here (default 53000).
• HyperDeck — Remote Control must be enabled in the deck's own Setup menu.
• Resolume — Preferences → Web Server → Enable Web Server.
• ProVideoPlayer (PVP) — the connection needs the HTTPS port from Preferences → Network API, not the plain HTTP port PVP also exposes; entering the HTTP port here will not work even though PVP is otherwise reachable.
• FreeShow — Settings → Connection → Remote must be enabled.

If the source-side setting is confirmed on and the dot is still red, re-check the port: a source with a non-default port (someone changed QLab's OSC port from 53000, for example) won't connect on the pre-filled default.

A connection is green, but an External timer isn't showing anything

That's a Chapter 4 problem, not a Chapter 3 one — a connection only defines where a value can come from. Confirm the External timer actually has that connection selected as its Source, and (depending on the source type) has the layer/cue/region field underneath it filled in — an External timer created without ever opening its settings panel has no source selected at all and can't display anything by design.

A remote ClockBridge source never appears as an option

Two separate requirements have to both be true: the remote server has to be running and reachable at the address/port entered (default 4500), and the specific timer you're trying to follow has to be marked Shared on that remote server (Chapter 4's Clock Preset section and Chapter 6's Feature Toggles both reference this same Shared flag). A remote server that's reachable but has no Shared timers will show a connected (green) status with nothing selectable in the Remote Source dropdown — that's expected, not a bug, until something on that server is actually shared.

Time from an external source looks consistently off by the same amount

Use the connection's Latency (ms) field (-5000 to 5000) rather than assuming the source is broken. It's worth checking whether the source reports in whole-second steps (ProPresenter, QLab, HyperDeck, and PCO Live all do) versus sub-second precision (ClockBridge, Resolume, PVP, FreeShow) — a whole-second source will always look like it's stepping rather than counting smoothly, which is a property of that source type, not a sync problem to chase.

I'm looking for a Resolume or PCO Live connection in the list and can't find it

Check for a "PP" badge instead of what you'd expect. On the /setup External Sources list (not the Chapter 4 control-panel source picker, which uses a different badge scheme), ProPresenter, Resolume, ProVideoPlayer, and PCO Live connections all share the same "PP" type badge — only ClockBridge (CB), QLab, HyperDeck (HDK), and FreeShow (FS) get their own distinct badges on that particular list.

Control Panel & Presets (Chapter 4)

A newly-created timer isn't assigned to any Clock Window

This is expected unless a Default Clock Window Per Type has been set for that timer type in the ⚙ Settings panel (or /api/defaults on the server side). Without a default set, a new timer is created unassigned and idle — assign it manually from the timer card, or set a default so future timers of that type auto-assign.

Loading a Preset replaced timers I wanted to keep

That's the intended behavior, not a bug to work around — a Preset (Chapter 4) is a full snapshot of the entire show (every timer and every Clock Window), and loading one replaces everything currently on screen. If you only want to reuse a single timer's configuration without touching the rest of the show, use a Clock Preset instead — it targets one API ID at a time and leaves everything else alone.

Applying a Clock Preset didn't do what I expected

Check which API ID it landed on. Loading a Clock Preset from the Presets ▾ menu asks for a target API ID and warns if that slot is already occupied before replacing it — if the wrong API ID was typed in, the preset lands on (and overwrites) a different timer than intended. The API ID batch editor in ⚙ Settings is the place to confirm which name currently maps to which number.

The API ID editor won't let me save

Duplicate or non-positive API ID values are flagged in red and block the UPDATE button — every timer needs a unique, positive numeric ID, since that's the same number Control Methods (Chapter 5) and Clock Presets use to address a specific timer. Fix the flagged row(s) rather than looking for a separate save error.

Control Methods (Chapter 5)

An OSC, RossTalk, or Companion command to stop/reset/adjust a timer silently does nothing

This is enforced, expected behavior for countdown-to-time and countup-from-time timers specifically — the server skips the command and logs a warning rather than erroring back (OSC and RossTalk don't get a reply channel to error on in the first place). If a button mapped to Stop, Reset, or Adjust isn't affecting a Time-mode timer, that's the guard working as designed, not a dropped command. Start/Display/Hide always work regardless of timer mode.

OSC or RossTalk commands aren't reaching ClockBridge at all

Both are off by default and have to be explicitly enabled on /setup, each with its own port (OSC: UDP 9000; RossTalk: TCP 7788). Before checking the sending device, confirm the matching Enable checkbox is on and the port on both ends actually matches — these are separate ports from the control panel's own 4500, so a script pointed at 4500 with an OSC address pattern won't reach the OSC listener.

A REST API call works from a browser or curl but a script gets 400s

The REST routes take a timer's long unique id in the URL path, not the numeric API ID used everywhere else in this manual (OSC, RossTalk, Companion). Look the id up first via GET /api/state — its timers[] list carries both id and apiId for every timer — rather than assuming the two are interchangeable.

Anyone on the network can control ClockBridge without logging in

That's not a misconfiguration to fix — there is no authentication on the REST/WebSocket API by design (Chapter 5). The actual security boundary is the network segment ClockBridge sits on. If timers are getting started, stopped, or retargeted by something other than your own show control, check what else has access to that segment (guest Wi-Fi, a shared office VLAN) before assuming the app itself has a bug.

Companion shows the right state but a button does the wrong thing

Companion keeps its own live copy of the server's state and acts on that, rather than asking the server on every press — this is what makes it fast, but right after a rocky reconnect (rare) that copy can briefly lag behind the server. If a single button seems to be acting on outdated info right after a connection blip, toggling the connection off and on in Companion forces a fresh state sync.

Preferences & Operator Handoff (Chapter 6)

A feature toggle I enabled on /setup isn't showing up for an operator

Feature Toggles, Feature Defaults, and Default Clock Window Per Type are all stored on the server and pushed live to every connected client the moment they change — no page reload needed. If an operator's control panel genuinely isn't reflecting a change after it's saved on /setup, check whether their control panel actually lost its connection to the server (the top-bar connection dot, Chapter 4, turns red when disconnected) rather than assuming the toggle itself failed to save.

An operator's control panel looks different from mine (skin)

This is the one preference in Chapter 6 that's deliberately not shared — Skins are remembered by each machine on its own, and never sent to the server. Every other machine connected to the same server can run a different skin permanently, and that's expected: there's no "house skin" setting on /setup. Reinstalling the app or clearing that browser's saved site data resets its skin to Classic; it has no effect on any other connected machine.

A capability I turned on isn't actually available to a new timer by default

Two different settings are involved, and it's easy to only touch one of them. Feature Toggles make a capability exist at all (a checkbox and its per-type grid on /setup); Feature Defaults decide whether a newly created timer starts out using it. Turning a toggle on doesn't retroactively enable it for timers that already exist, and doesn't make new timers use it either unless the corresponding Feature Default is also checked for that timer type.

Activation (Chapter 1)

These are the messages the activation screen can show after you click Activate. The code box is cleared of spaces and capitals for you, so a typo is the usual cause of the first one.

"That code wasn't recognized. Check for typos."

The code isn't one the activation service knows. Check it character by character against the message the Discord bot sent — codes use only the digits 0–9 and the letters A–F, so a 0 and an O are easy to mix up. Include the CB- at the start.

"That code's already been used, or this Server is already registered."

Two different causes show the same message:

• The code was already redeemed. Each code works for one install. Use /get-clockbridge in Discord for a new one, or ask whoever runs the beta.
• This Mac is already registered. If you've activated on this machine before and it's asking again (for example after a clean reinstall), the activation service remembers the machine. Contact ClockBridge/Reid and ask for the registration to be cleared.

"This code has reached its install limit."

You've used all the installs you're allowed in the beta. Contact ClockBridge/Reid if you need to move an install to a different machine.

"Couldn't reach the activation server — check your internet connection."

The Server couldn't get an answer in about 15 seconds. Check that the machine is online and that nothing on your network is blocking outbound HTTPS, then click Activate again. This only happens during activation; an already-activated Server never needs the internet to run.

"Unexpected response" followed by a number

The activation service answered with something the app didn't expect. Wait a minute and try once; if it repeats, contact ClockBridge/Reid and include the number from the message.

The User app says "Server not activated"

The Server the User app is connected to is running but hasn't been activated with a beta invite code. The User app has no activation screen of its own, so it can only tell you. Open that Server's address in a browser (or use Open ClockBridge on the Server computer) and enter an invite code there. The User app's message goes away on its own within a few seconds of activation, or click Check again. If you're connected to the wrong Server, use Connection Settings to change it.

The activation screen came back on a Server that was working

The beta program ended your access, and the screen shows a message saying your activation is no longer valid. This takes effect the next time the Server app starts. Enter a valid invite code to continue, or contact ClockBridge/Reid if you think your access was ended by mistake.

Updates (Chapter 7)

After clicking Restart, the User app still shows the old version

This is a known relaunch issue on macOS — installation and signature verification succeeded, but the relaunch step doesn't always take. The banner itself tells you what to do: quit ClockBridge (the User app) and reopen it manually to finish landing on the new version. See Chapter 7 for the full update flow.

Update from Server says no update is available, but I know the server has a newer build

Updates are own-platform only — a Server app only carries the User-app installer for the platform it itself was built on. A Windows User app talking to a Mac-hosted Server (or the reverse) will always report "no update available," identical to actually being current, because there's no matching installer for it to offer. This isn't a bug to chase; it means the Server and User app need to be reinstalled from platform-matched installers if they're on different OSes.