Troubleshooting¶

Symptom → likely cause → fix. Listed roughly by frequency.

"Runtime won't start"¶

Error: "show file not found"¶

You gave the wrong path. Verify the .ishow file exists at the path you specified.

Error: "show failed validation with N error(s)"¶

The .ishow references something that doesn't exist (a look that was deleted, a node id that changed). Open the file in Studio and fix in the Validator (Ctrl+8).

Error: "unsupported schema"¶

The .ishow was saved by a newer version of Studio than this Runtime supports. Either update Runtime, or have the designer save with the same Studio version.

Error: "EADDRINUSE: address already in use"¶

Another process is on port 7880. Either kill it, or run Runtime with --port 7881. If a previous Runtime crashed without releasing the port, reboot or wait 30 seconds.

Console flashes briefly and disappears¶

Runtime crashed before logging anything. Run from a Command Prompt manually so you can see the error.

"Operator dashboard shows red disconnect dot"¶

Most common: Runtime isn't running¶

Check the Runtime PC. The Runtime window or service should be visible in Task Manager. If not, Runtime crashed or wasn't started.

Wrong URL¶

Are you using the right IP? The dashboard URL is http://<runtime-ip>:7880/. Check the Runtime PC's IP via Network settings.

Network firewall¶

Try curl http://<runtime-ip>:7880/status from the operator's device. If it times out:

Windows Firewall on the Runtime PC may be blocking inbound — see Runtime Install for the firewall rule
Tablet is on a different VLAN/Wi-Fi than the Runtime PC

Tablet on wrong Wi-Fi¶

Operator tablet on the venue's guest Wi-Fi instead of the show network. Common at venues with multiple SSIDs. Reconnect to the right one.

"DMX cue fires but the lights don't move"¶

Network: IGMP snooping not enabled¶

Most common cause at venues with managed switches. Without IGMP snooping, sACN multicast either floods (network falls over) or gets filtered. Both look like "DMX broken." Enable IGMP snooping on the switch.

Wrong universe¶

Studio writes channel addresses; Runtime sends them on universe 1 by default. If your fixtures are listening on universe 2 or higher, they won't see anything. Multi-universe support is a v0.2 feature.

Fixtures pointed at the wrong network interface¶

Runtime joins the multicast group on whichever network interface it picks first. On a PC with multiple NICs (Wi-Fi + Ethernet), it might pick wrong. Disable Wi-Fi or set a metric to force Ethernet.

Look has no keyframes¶

The cue has a valid lookId but the Look itself is empty. Check Studio → Lighting Looks (Ctrl+9) → does the look have keyframes? Validator will warn about this.

Verify with sACNView¶

Free Windows tool. Listens on the network and shows what's actually being sent on each universe. If sACNView shows the right values when you fire a cue, the problem is downstream of Runtime — fixtures, addressing, or cabling.

"Audio plays but it's silent / wrong speaker / distorted"¶

Audio Node not connected to speakers¶

Walk to the Audio Node. Verify:

Audio Node's status LED is green
Audio cable is plugged into both Node and amp/speaker
Amp/speaker is on, set to the right input

Volume too low¶

The cue's volume field is 0..1. Try volume 1.0 in Studio. Then check the venue's amp gain.

Distorted at high volume¶

Verify the Audio Node's output level matches the amp's expected input level. A line-level Node into a mic-level input will distort. Use the right cable type.

"File not found" errors in the dashboard log¶

The filename in the cue doesn't match what's on the Node. Check the .ishow filename vs. what was pushed. See Media Distribution.

Audio cuts off after a few seconds¶

The Node may have hit a media file error. Re-push the file using the Media Push tool. If it persists, swap the Node with a spare and contact support@immersecontrol.com.

"Video shows black screen"¶

HDMI not connected at boot¶

Connect display first, then power on the Video Node. The Node needs an attached display at boot to enable HDMI.

Display in standby / wrong input¶

Walk over and look at it. This is the #1 "video broken" cause that nobody admits to.

Wrong cable / damaged cable¶

HDMI cables fail. Try a different cable. Long runs may need an HDMI extender or fiber-HDMI.

Resolution mismatch¶

Some displays don't accept all output modes. If the Video Node outputs 4K and the display is 1080p only, you may get a black screen. Check the display's accepted modes and adjust.

"GPIO doesn't trigger anything"¶

Wrong channel in the cue¶

Designer authored channel gp4; your wiring is on a different channel. Match the wiring to the cue or vice versa. The Node ships with a labeled wiring diagram showing which screw terminals are which channel.

Wiring backwards¶

Verify with a multimeter — pulse the cue, see if voltage on the output terminal actually goes high. If yes, your downstream device wiring is the problem.

Pulse too short¶

Cue's pulse duration defaults to 250 ms. Some relays need longer to actually engage. Set the cue's dur to 500 ms or 1.0 seconds.

"Cue fires but nothing happens at all"¶

A cue's fire event hit Runtime, but no downstream side effect occurred. Check Runtime's log. The log line for the cue tells you what was attempted:

"fire DMX cue → applied look" — Runtime sent sACN. If lights didn't move: see DMX section above.
"GPIO ... → fail" — HTTP call to a Node failed. See "Node unreachable" below.
"GPIO ... → ok" but relay didn't click — see GPIO wiring section above.
"audio playback deferred" — you're on Runtime v0.1.x which doesn't actually fire audio yet. Audio playback is shipping in v0.2.

"Show was working yesterday, now it isn't"¶

Something changed. Find what.

Did the network change?¶

Network admin pushed a new switch config? IPs reassigned by DHCP?

Re-validate Node reachability: visit http://<each-node-ip>/health for each Node
Compare current IPs to the venue map you wrote down during install

Did the show file change?¶

Designer saved a new version that overwrote the working one?

Check modification time on current-show.ishow
Run the Validator on the current file in Studio
Roll back to a known-good archived version

Did a Node fail?¶

Hardware does fail eventually. The Node's LED tells you:

Green: ready
Amber: booting (under 60 seconds)
Off: power problem
Red: hardware fault — swap with spare, contact support

Windows Update happened¶

Windows applied an update overnight and rebooted. Runtime might not have auto-restarted. Check Task Scheduler or the configured auto-start mechanism.

Node unreachable¶

Symptoms: Runtime log shows "GPIO call failed: connection refused" or "audio call timed out."

Walk through:

Power LED on the Node — green = ready, off = no power
Network LED on the Ethernet port — should be lit; verify cable seated at both ends
Switch port — should show link/activity for that port
IP address — visit http://<node-ip>/health from the Runtime PC. If timeout: DNS/IP issue. If 404: wrong nodeId. If 200: Node is fine, problem is elsewhere.
Swap with spare — if a Node is genuinely failed, hot-swap takes under a minute. See Node Setup.

"Operator can't fire cues"¶

Dashboard shows green dot but GO does nothing¶

Try curl -X POST http://<runtime-ip>:7880/go from the operator's device. If 200 but show didn't advance, Runtime returned {ok:false,reason:...} — read the response.

"no cue to fire — add one first"¶

Cue list is empty or the pointer is past the last cue with no wrap. Press STOP to reset.

"Can I fix this remotely?"¶

For Runtime issues:

Remote-Desktop / TeamViewer / AnyDesk into the Runtime PC
Or use the HTTP API directly from anywhere reachable

For Node issues:

Visit the Node's /health URL for a quick status check
For deeper diagnostics, contact support@immersecontrol.com with the nodeId and the symptom

For everything else: a phone call to someone onsite. There's no built-in remote-recovery for sACN/HDMI/wiring issues; those need physical access to verify.

When to call IMMERSE support¶

Email support@immersecontrol.com with:

Studio version, Runtime version (the About menus tell you)
The Runtime log file from when the issue happened
The Node's nodeId if a specific Node is involved
A description of what was supposed to happen vs. what did
Whether it's reproducible or one-time

If a show is happening right now and you've exhausted the troubleshooting above: STOP the show via the operator dashboard, blackout lights manually, get the audience comfortable, then start working the problem with a clear head. A 5-minute pause in a show is recoverable. A panicked operator hitting random buttons is not.