Troubleshooting
Operator recovery steps for common problems. Each entry follows the pattern: what you see → what it means → what to do.
An output won't connect
What you see — An output row in Network shows a red or amber status. The EdgeBar displays a circuit-breaker warning chip. Commands sent to that output have no effect.
What it means — CueSync cannot reach the device at the configured address. After several failed connection attempts the circuit breaker opens, which stops further attempts until you intervene. This protects the network from a flood of failing commands.
What to do
- Check the device is on and on the network. Ping the host from your laptop, or open the device's own UI, to confirm it is reachable.
- Verify the host and port. Open the Output Editor (click the output row in Network). Confirm the IP address and port match the device's actual network settings.
- Test the connection. Click Test Connection in the Output Editor. CueSync sends a probe message and reports success or failure immediately.
- Reset the circuit breaker. If the breaker is open and you have fixed the underlying problem, click Reconnect on the output row. The breaker moves to a recovery state and retries.
- Check Diagnostics. Open the Diagnostics screen for a log of every connection event, including heartbeat misses and message failures. This log survives screen navigation and is useful for post-show review.
- Run Flight Check before the show. The Flight Check dialog tests all outputs in sequence and surfaces any that are unreachable before the show starts.
A cue isn't firing
What you see — The show is running, beats are counting, but a specific cue never fires (or fires at the wrong moment).
What it means — The cue's trigger condition is not being met, the cue is disabled, or an edition restriction is blocking execution.
What to do
- Check the cue is enabled. In the Cues screen, confirm the toggle on the right of the row is on. A disabled cue is skipped silently.
- Check the trigger type and settings. Open the Cue Editor and review the trigger. Common mismatches:
- A Beat trigger set to beat 1 of every bar fires only on beat 1, not every beat.
- A BPM Range trigger fires only when the tempo enters the range — if the tempo was already in range when the stack reset, it will not fire again until it leaves and re-enters.
- A Phrase trigger fires at the start of the named phrase type. If the track has no phrases of that type, it never fires.
- Check stack position. Most triggers (Beat, BPM, Phrase, Energy) evaluate only the next cue in the stack. If a cue higher in the stack is never firing, the cues below it are also blocked. Identify and fix the stalled cue first.
- Hot Cue and MIDI triggers are exceptions. These can fire out of order — if yours is not firing, confirm the correct hot cue label or MIDI message is configured and the source is sending.
- Check your edition. Some trigger types and workflow features are gated by edition. A cue that was authored on a higher edition and then loaded on a lower one may not fire. The Cue Editor shows a gate indicator when this applies.
- Watch for error notifications. If the cue fires but the output fails, a notification banner appears in the top-right corner. If you missed it, open Diagnostics to review the error log.
A show won't start
What you see — Pressing GO in Run Mode does nothing, or a pre-show gate blocks playback and will not let you proceed.
What it means — One of two situations: a pre-show readiness check is blocking start, or one or more cues are not marked as Ready.
What to do
- Run the pre-show check. If you see the Pre-Show Review screen, work through the checklist it presents. Items typically include unconnected outputs, cues still in Drafted or Tested state, and missing venue profile confirmations. Each line is actionable — click it to jump to the relevant screen.
- Mark cues as Ready. The Cue Editor has a ready-state control: Drafted → Tested → Ready. A show that requires all cues to be Ready will block until you have reviewed and promoted them. Select cues in the Cue stack and use the bulk-edit button to promote multiple cues at once. Note: the readiness check runs only when you start a stopped show — resuming from a pause continues without re-running the gate, so cues that were already passed are not re-evaluated.
- Check your edition. Run Mode is a Theatre and CueSync Production feature. If your edition does not include it, the screen is locked.
- Confirm outputs are connected. Run Mode will warn when outputs are unreachable. Fix connectivity first (see An output won't connect), then return to the pre-show check.
No sound at the venue
What you see — Local audio plays in the app (the playhead moves, the waveform animates), but nothing reaches the speakers.
What it means — The master output is almost always routed to the wrong device — most often a virtual/loopback device (BlackHole, VB-Cable, VoiceMeeter) left over from a streaming or recording setup, or a saved device that is no longer connected.
What to do
- Check the master output device. Open Settings → Audio. Devices badged Virtual are loopback drivers — audio sent there does not reach speakers unless another app is listening. Pick the real interface feeding the PA.
- Watch for the missing-device notice on startup. If the saved output device was not found, CueSync names it in a notification rather than silently falling back. Re-select the right device after changing hardware.
- Enable the Silent-Track Warning. Under Settings → Audio → Reliability & Sync, this alerts you whenever a playing track stays silent for more than a second — catching corrupt files and wrong routing during soundcheck instead of during the show.
Reference video won't play
What you see — The Show Editor's reference video pane shows "Install VLC to enable reference video" or stays black.
What it means — The pane plays video through your system's VLC installation. Without VLC (or with a broken install), CueSync cannot decode the footage. The show itself is unaffected — reference video is an editing aid and is never sent to outputs.
What to do
- Install VLC from videolan.org (the standard desktop app), then reopen the show.
- Check the file plays in VLC itself. If VLC can't play it, transcode to a common codec (H.264 MP4).
- Check the offset. If video plays but looks out of sync, open the pane's gear and adjust the offset — a positive value means the footage has pre-roll before the part's audio starts.
I lost my work
What you see — CueSync quit unexpectedly, or you closed the app without saving, and changes are missing.
What it means — CueSync saves a recovery snapshot periodically in the background. If the app exited uncleanly, that snapshot is newer than the last manual save.
What to do
- Check the Recovery dialog on launch. When CueSync detects a newer recovery snapshot, it shows the Recovery dialog on startup. Choose Restore to load the snapshot. The dialog shows the timestamp of the snapshot so you can judge how much work it covers.
- Browse backups. CueSync also maintains dated automatic backups separate from the recovery snapshot. Open Settings → Projects & Backup → Browse Backups to see a list of dated backup files and restore from any of them.
- Save frequently. Press
Cmd+S(macOS) orCtrl+S(Windows) to save at any time. Before a show, save once more and confirm the file timestamp. - If the app crashes repeatedly. Note the exact steps that caused the crash and report them via Settings → About → Send Feedback. Include the show file if possible (with any sensitive cue names removed).
Related
- Diagnostics — connection logs and circuit-breaker state
- Network Outputs — output configuration and Test Connection
- Cues — cue stack and ready-state management
- Run Mode — Theatre GO button and pre-show check
- Glossary — definitions for circuit breaker, freewheel, and other terms
Looking for a quick fix?
The Help Center has short task-focused articles and a support team that responds within 24 hours.