Troubleshooting

Quick fixes for problems that show up often in rehearsal and on show machines. For preferences detail, use the linked Settings pages.

Update check fails with “Could not reach the update server”

Help & Support -> Check for updates… (or an automatic check) needs HTTPS access to the release manifest (latest.json) on the Samba website.

Apex domain 301 to www

Older builds requested https://samba-sync.com/.... That host 301-redirects to https://www.samba-sync.com/.... Samba’s HTTP client often does not follow that redirect, so the check fails with:

Could not reach the update server. Check your internet connection.

Even when the machine is online.

What to do:

Situation	Action
Samba 2.5.177 or newer	Use Help & Support -> Check for updates… again. These builds prefer the www host so the 301 is avoided
Older than 2.5.177	Download the installer manually from www.samba-sync.com/installers and run it over the existing install
Still failing on a new build	Check firewall / proxy / offline show LAN; open the installers page in a browser on the same machine

See Updates for automatic checks and installer platforms.

Missing media / Waiting for Dropbox

Clips store paths, not audio/video bytes. If the file is not at that path:

Label	Meaning
Missing	File not found at the stored path
Waiting for Dropbox	Path points at a Dropbox cloud placeholder that is still downloading / hydrating

Cues still run. Missing media does not remove markers from the show.

Fix:

Confirm the project folder and Media/ tree match the machine that saved the show
For Dropbox: wait until the file is fully local (not online-only), then reopen or scrub again
Relink in File -> Media Manager… if the file moved
Prefer Copy to Media when adding files so relative paths stay portable

Details: Media and Media Manager.

Audio device unavailable / ASIO vs DirectSound

Symptoms: no sound, open failure after Preferences, or a red-style unavailable device row.

On Windows	Guidance
ASIO	Prefer for show playback and low latency when a working ASIO driver is installed
DirectSound (or other built-in types)	Fallback for simple stereo monitoring when ASIO is missing or broken

Checklist:

Edit -> Preferences… -> Audio device - pick a device that exists now (reconnect the interface if needed)
Close other apps that hold the device in exclusive mode
Match sample rate to your media / LTC gear when possible
Increase buffer size if you hear dropouts on a busy machine
On macOS, use the Core Audio device list (no ASIO type row)

See Audio device.

LTC / MTC not following

If the timeline does not slave to external timecode, or outgoing TC does not drive other gear:

Incoming (Samba follows)

Edit -> Preferences… -> Timecode - enable Follow incoming Timecode
LTC: correct Input device, LTC input channel, and Input gain (clean LTC only - not program audio)
MTC: select the correct MTC input device (not disabled)
Art-Net: correct Art-Net receive port and that packets reach this machine
Confirm the master is actually generating TC at the expected frame rate

Incoming follow is not the same as cloud Follow user (collaboration awareness).

Outgoing (Samba is master)

Enable outgoing timecode from the Player when required
Transport must be playing for LTC / Art-Net out (see Timecode preferences hint)
Keep LTC output on a dedicated channel; do not mix music onto that same channel (Track audio output on Audio device)
Trim LTC gain if readers jitter or drop
For MTC out, select a real MTC output device

See Timecode and Playback.

Cloud markers missing after reopen

On a cloud project, cues live in server structure (and a local companion .samba). Media stays local.

If markers look empty after reopen:

Confirm you opened the same cloud project and are signed in
Use File -> Save to Cloud (Ctrl+S) after cue edits so the server has your latest markers; structural edits also auto-sync after a short delay
Wait for sync / reopen once if another machine just pushed changes
Prefer Export Local Copy… for an offline backup before risky folder moves

Samba is designed not to force an empty cue list over a project that still has cues on disk or on the server (empty UI buffers during cloud open must not wipe imported markers). If something still looks wrong, do not repeatedly save an empty list hoping it “fixes” sync - reopen from cloud, or restore from a known-good local export, then save again.

See Cloud projects and Cues.

MCP: Samba must be running

Cursor (and compatible hosts) talk to Samba over a localhost HTTP MCP endpoint. Samba must already be open; the host should not spawn a second window for the normal Cursor path.

URL:

http://127.0.0.1:17332/mcp

Check	Detail
Samba running	Start Samba first, then connect the MCP client
URL exact	Host `127.0.0.1`, port `17332`, path `/mcp`
Connections page	Edit -> Connections… -> Web & AI MCP documents the Cursor URL
Stdio	Optional `--samba-mcp-stdio` is only for hosts that spawn Samba themselves (for example Claude Desktop)

See Connections.

Capture UI for manual (Help & Support)

For documentation screenshots that match the live UI:

Arrange the workspace (panels, theme, sample content)
Help & Support -> Capture UI for manual…
Choose an output folder
Samba writes separate PNGs (workspace, panels, player buttons, cue types, and more) and reports what was saved

For this public manual’s assets, capture into manual/public/screenshots when working from the Samba-Sync repository.

Also listed under Menus and First launch.