Troubleshooting

What this does: the show-night checklist, by area. Each block is ordered: check the first line first. Every page in these docs also ends with its own When it goes wrong list.

Before anything else

• Something is firing that should not? ⇧Esc is Panic. Fix it after.
• Which build? Helm Cues → About Helm Cues. Then read What’s new: it may already be fixed.
• What to send? Help → Save Support Bundle… One zip: log, crash reports, settings, devices, the open project. No keys, sign-ins or media. See Diagnostics and support.
• Where is the project? ~/Library/Application Support/ShowLink Cues/shows/<id>.json. See Technical reference.
• Support: helm.show/support. Help → Report an Issue… opens it with the app and version filled in.

Where each page’s fixes live

Area	Page
First show, setup panel	Getting started
Projects, running orders, versions	Projects and shows
Cues, stacks, selections	Build
Beat grid, tempo	Beat grid and tempo
Media, lanes, Locate…, Trash	Media and lanes
Live, GO, arming	Live
Monitor windows, video out	Monitor and video outputs
Timecode out and chase	Timecode
The desk	grandMA3 setup · grandMA3 plugin
Second machines, iPads, TAKE	Sessions · Helm Monitor
Pairing, sync, uploads	Cloud sync
Updates, rollback	Updates

Licence and updates

”Capped at 3 tracks per project”

The banner reads “You’re using Helm Cues unlicensed — local shows only, capped at 3 tracks per project.” Adding a 4th track is refused: Free mode: a project holds 3 tracks. Activate a licence to add more.

1. Activate on the banner, or Settings → Licence → paste the HELM-CUES-… key → Activate.

2. Or sign in to Helm Cloud. A licence on the account arrives with it.

3. Offline more than 7 days: reconnect for one minute, then Refresh.

4. “This key is on 3 devices already.” Email support with the key’s last four characters and the device to drop.

See Accounts and licences.

The update is not offered, or a build is worse

1. Helm Cues → Check for Updates…

2. “Update check failed”: usually no network. The app is unaffected.

3. A new build misbehaves: Settings → Updates → Reinstall previous version. One step back. Shows and settings stay as they are.

See Updates.

Projects and files

The project will not open, or opened empty

1. Open it if you can, then File → Restore from Backup… and pick a time before it broke. The state you leave becomes the newest backup.

2. Deleted? File → Restore Deleted Show…

3. No backup yet: Cues keeps the last four saves as shows/<id>.json.bak, .bak.1 to .bak.3. Quit. Move the broken <id>.json aside. Copy the newest .bak to <id>.json. Launch.

4. A project only ever opened on another Mac is not on this one. Project Manager → Cloud only → Download, or import its .helmpkg.

5. Send the file. It holds no secrets beyond the show’s names.

See Backups and show packages.

File names show as long codes

Fixed. Earlier builds showed a long code instead of the file name in the Media Library, track details and the Project Manager.

1. Update Cues. Every list shows the real name again. Nothing was lost.

2. Linked to the cloud? Push once (⇧⌘U). The cloud puts the real names back.

Live says No active show.

Show page (⌘3) → pick a running order → Set active. See Projects and shows.

Timecode

No timecode on the desk

1. Settings → Audio Devices → Enable LTC Output is ticked. It ships off.

2. Output Device is the interface wired to the desk. Generated LTC channel is the channel on the cable.

3. Single Output: the music is on the other channel of the same device. Dual: the LTC device is the second interface.

4. Live page: LIVE is armed and the track is loaded. Timecode runs only while the transport runs.

5. Live header reads TC ON. The output pill lists each output, e.g. LTC on. No timecode output means the desk gets nothing.

6. The desk’s timecode pool rate equals the project’s Frame rate (View → Project Settings…). 25 against 30 reads as nothing or nonsense.

7. The desk’s LTC input gain. A muted interface output sends nothing.

8. MTC instead: Settings → MIDI Devices → Enable MTC Output → MTC Output Device.

9. Art-Net or MIDI Clock: Settings → Timecode. Both ship off. Outputs now shows what is running.

10. The desk drops out on every pause: the show is on Mute. Settings → Timecode → When stopped (this show) → Hold last frame.

Send: build, interface model, frame rate, a photo of the desk’s timecode pool.

MTC drift or jitter

1. Frame rate. 29.97 DF against 30 drifts 3.6 s per hour. Match both ends.

2. 23.976 is sent as the 24 code. A desk set to 23.976 reads it as 24.

3. Settings → Audio Devices → Playback sync: the ±0.5 frame trim between the audio clock and the timecode clock. Measure, then set.

4. USB MIDI through a hub shares bandwidth with everything on it. Use a direct port.

5. Network MIDI over Wi-Fi jitters. Wired, or local.

6. Chasing MTC in: MTC Input — Chase upstream timecode should read LOCKED — receiving timecode. Listening… (no signal locked yet) for more than a few seconds means the incoming rate does not match.

7. Measure it: Help → Diagnostics → Clocks, last 60 s → MTC − expected. Read p95 against one frame and ms/min for drift.

Send: both frame rates, USB or Network MIDI, how much drift over how long, and Copy report from Diagnostics.

See Timecode.

The grandMA3 desk

The desk shows no session to connect to

1. Cues: View → Sessions… (⇧⌘D) → Host this show first.

2. macOS firewall: Helm Cues must accept incoming connections.

3. Same network. No router between Cues and the desk.

4. Type the Cues Mac’s IP into the desk’s Connect… dialog. That works without the session list.

The desk connected, nothing arrives

1. Help → Check MA3 Connection… It checks the session, Allow, the plugin version (0.15.0 or later) and that the desk answers. Fix the first red step.

2. Sessions → Requests: a new desk waits for Allow while Desks need approval before they pull is on.

3. Sessions → Devices: the desk reads Joined. Not Blocked, not Joined · driver gone.

Cues not firing on the desk

1. Timecode reaches the desk. See No timecode on the desk.

2. Devices: the desk reads Joined. Joined · auto-sync off means edits do not reach it: ⋯ → Resume auto-sync. Resume catches the desk up once.

3. Desk section → Push now. Check the sequence exists on the desk and is assigned to the timecode show.

4. The event’s hour equals the track’s timecode offset.

See grandMA3 setup and grandMA3 plugin.

Sessions

LINK LOST on a peer

A peer stopped hearing the host. “LINK LOST — the host is not reachable. The playhead is frozen.”

1. The playhead freezes on the last known position. The host is unaffected.

2. Check the cable, the switch, the host. The peer reconnects on its own: “Link restored.”

3. Guest Wi-Fi (venue, hotel) joins and then drops. Put the peer on the show switch.

4. The host Mac is on two networks: Show join code… → Interface must be the one the peer is on.

The host is gone: TAKE

Only on a peer that joined as standby at operator or better.

1. After 5 s of LINK LOST it shows Host lost n s — TAKE?

2. Press TAKE, then CONFIRM TAKE within 4 s.

3. This Mac hosts the show under the same session name and passcode, starts the desk bridge as the old host had it, and parks at the last position.

4. Arm Live and GO when ready.

5. Other Cues peers: Rejoin in their session list.

Name the risk: never automatic. If the old host comes back there are two hosts. Stop it.

See Sessions.

A device cannot join

1. Join policy Ask: the device asks. Press Allow on the toast <device> wants to join, or in Requests.

2. Deny tells the device no. It does not ask again by itself.

3. Members only: no device on the network can ask. Members join with a Helm Cloud sign-in.

4. A device you approved before rejoins without asking. Remove approval in its ⋯ menu makes it ask again.

Live, Panic and media

Live blocked: media not local

The toast reads Live blocked: …. Live will not open and LIVE will not arm until every file the show uses is on this Mac and checks out.

1. Media is still being verified or Media is still downloading (3/7): wait for the pill to clear.

2. n media files not local: open the Media Library (⇧⌘L). The banner lists each file: missing, downloaded copy is damaged or could not be read.

3. · cloud has it: press Download. Signed out? Pair first.

4. Not in the cloud: Locate… the file on a drive. A file that is not the recorded one asks before it is used.

5. Deleted by mistake: Trash → Restore.

6. Media could not be verified (…): the check itself failed, so Cues blocks Live to be safe. Send the support bundle.

7. Already armed when a file went missing: Live stays open. The check runs when you enter Live and when you arm.

See Media and lanes.

Space does nothing on Live

Arm LIVE first. Space is GO, and GO needs an armed player. See Live.

Audio from one side, or silent

1. Track Details → Routing → Music out: Both, not Left or Right, unless the right leg is LTC on purpose.

2. File LTC out on a track with no LTC in the file: set it Off.

3. A lane: muted, soloed out, or locked. Solo across lanes is one group.

Cloud sync and uploads

Data use is high

1. Settings → Helm Cloud → Uploads → Uploaded from this Mac: read Today and This week.

2. Set the project to Ask for batches over 1 GB or Off.

3. Keep Daily upload limit on. The default is 10 GB.

4. On a metered line, answer the upload prompt with Not on this network.

5. Big files you never need in the cloud: Media Library → right-click → Keep on this Mac (don’t upload).

Name the risk: Cues builds before 0.2.16 could restart the same upload without limit. Update first. See What’s new.

Uploads stopped or paused

Pill	Do
Uploads paused — network (resumes …)	Check the line. Resume to send now.
Uploads paused — rate limited (resumes …)	Wait. It resumes by itself.
Uploads paused — daily limit reached	Wait for midnight, or Resume to send anyway today
Upload failed — <file>	Tries spent. Retry.
Uploads stopped — cloud storage full	Free space on app.helm.show, then Retry
Uploads stopped — sign in to Helm Cloud	Pair again, then Retry

See Cloud sync.

”You no longer have edit access to this cloud project — changes stay on this Mac”

1. The project stays linked. Auto-push stops for it. Every change stays on this Mac.

2. Ask a project owner to restore your Editor role.

3. File → Push to Helm Cloud (⇧⌘U). Or Unlink on the toast to keep it local only.

Signed out of Helm Cloud after 90 days

1. Pair again on the prompt.

2. Authorize on app.helm.show/pair.

The show, Live and the desk never depend on the cloud.

Sync conflict

Sync conflict · n track(s). Other tracks keep syncing. Keep mine or Keep theirs per track. Settle them before you quit: a relaunch clears the list.

Pairing fails

1. Builds up to 0.2.11 cannot pair. Update, then pair. Already-paired devices keep working.

2. Helm Cues → Account… → Sign in to Helm Cloud.

3. “Browser didn’t open?”: go to app.helm.show/pair and type the code.

4. Pairing code expired — try again.: codes last 10 minutes. Try again.

5. “Device paired” in the browser but Cues still waiting: the Mac cannot reach app.helm.show. A Wi-Fi login page, a proxy or a blocked network.

Send: build, the exact text in the Cues panel, whether the browser showed “Device paired”.

When it goes wrong

None of the above fixed it? Help → Report an Issue… opens helm.show/support with the app and version filled in. Send one email: what you did, what you expected, what happened, whether it is a show night, and the zip from Help → Save Support Bundle… Subject line: app, version, symptom.