Troubleshooting

Start with the section that matches your problem. If nothing here helps, see getting help at the bottom.

The app won't open or shows a blank window

1. Close any other copy, including development builds. Try launching once more.
2. Confirm that you installed the Windows release installer from the official releases, rather than a source archive or an update package.
3. For a blank Windows interface, check that Microsoft's WebView2 Runtime is installed. Install or repair it, then reopen MultiShock.
4. If this began after installing a plugin, close MultiShock and move that plugin's directory, DLL, or archive out of the plugin folder.
5. Keep the newest logs before resetting anything. If configuration is the problem, use configuration recovery to preserve the old file and try defaults.

For a source build that does not launch, first check the SDK and workloads in building from source. Reinstalling the app does not necessarily replace the per-user configuration.

Logs

MultiShock writes a log file each time it starts, in %LocalAppData%\PiShock\MultiShock\logs\. To open the folder, go to Settings → Logging and click Open folder.

• main-<date and time>.log has host messages at the configured detail level.
• plugins-<date and time>.log has plugin-category messages when Separate plugin logs is enabled; otherwise those messages go into the main log.

The Logging tab also sets the Detail level, how many Files to keep (10 by default), and the Maximum file size. These changes take effect after you restart MultiShock.

Logs include your PiShock username and device and shocker IDs, so check them before posting them publicly.

If there is no new file, enable Write logs to disk, restart, and reproduce the problem. Debug and Verbose capture more detail but produce larger files. Keep the files matching the time of the failure; a log from the next successful launch may not contain it.

Diagnostics page

Settings → Advanced → Debug & diagnostics → Open (or search for "Debug" with Ctrl+K) shows what MultiShock is connected to:

• Status: whether you're signed in, the connection to PiShock, how many USB devices are connected, and how many shockers are loaded. Click Refresh to update it.
• Plugins: the plugins that were found, and Recent Plugin Errors.
• Performance: runtime samples and operation timings while capture is enabled.
• System: the app base directory, .NET version, operating system, and process architecture.

These tools can expose identifiers and traffic. Review a screenshot or report before sharing it, and avoid sending raw test commands to live devices casually.

Signing in

You're signed out every time you start MultiShock. MultiShock checks your sign-in when it starts, and if that check fails for any reason, including being offline, it signs you out. Make sure you're online, then sign in again with Sign in to PiShock.

Sign-in fails. Signing in opens your browser. Finish signing in there within 5 minutes; after that you'll see "Login timed out after 5 minutes". If no browser opens, check that Windows has a default browser, then try again.

The login flow needs access to https://login.pishock.com and a secure WebSocket connection to wss://relay.pishock.com. A browser login page loading successfully does not prove the app's relay connection works. If a VPN, proxy, firewall, or network filter is involved, check its blocked requests and try a known-working connection; do not disable system protections as a general fix. The app does not require manually pasting a token into a configuration file.

Signing in with a different PiShock account clears your devices and shared shockers, along with their settings.

Connection to PiShock

The sidebar shows Connected when you're signed in and the live connection to PiShock is open, and Reconnecting when it isn't. It doesn't reflect USB hubs or plugins.

Commands using the disconnected network connection are dropped rather than sent later, and the Test button can still say "Sent". A working USB connection can continue carrying local commands while the WebSocket reconnects. Check the Status tab on the diagnostics page, then use Settings → General → Restart now if the connection does not recover. Sign out and back in only when needed: signing out clears saved device and shocker settings.

USB hubs

MultiShock looks for PiShock hubs plugged in by USB after you sign in. Serial setup continues even if the live PiShock WebSocket is reconnecting. It tries each new USB serial port once, when it appears. If another program is using the port at that moment, such as a serial monitor, a firmware flasher, or another copy of MultiShock, MultiShock can't open it and won't try again.

1. Close other programs that use serial ports.
2. Make sure you're signed in and using a data-capable USB cable.
3. Unplug the hub and plug it back in, or restart MultiShock.

In the log, look for "New device detected" and "Got info from" for a working hub, or "Serial connection error" when the port couldn't be opened. Hubs that can't be reached over USB are still controlled over the internet.

Devices and shockers

• The Devices page says "Sign in first". Sign in from the sidebar.
• "No devices yet". Click Sync from PiShock.
• A shocker shows Inactive. Tick both the device's and the shocker's checkboxes, then click Save changes.
• New shockers stay Inactive after syncing. Sync saves new shockers but doesn't load them. Change any setting and click Save changes, or restart MultiShock.
• Shared shockers are missing. Open Shared with me and pick the person under Add shared shockers. New shares aren't added automatically.

Flow errors such as "No shockers loaded" or "None of the selected shockers are currently loaded" mean the same thing: check the Devices page.

Plugins

A plugin doesn't appear. Open the diagnostics page → Plugins → Recent Plugin Errors. Check this list even if the log files show no loader error: the desktop loader is created before the application's normal logger is attached, so early failures may be absent from file logs. Plugin-authored logs remain useful for failures after initialization. Common causes:

• "…is not compatible with this MultiShock version, SDK, or operating system": update MultiShock, or install a version of the plugin made for yours.
• "…is installed twice": remove one copy from the plugin folder (Manage plugins → Plugin folder).

A plugin's pages are missing from the sidebar. New plugins' pages are hidden until you turn them on. See showing a plugin's pages.

Installing or updating fails. The message explains why, such as an incompatible version. Plugins marked Incompatible in Browse don't support your version of MultiShock.

Turning a plugin on or off does nothing. The change applies the next time MultiShock starts.

A plugin crashes MultiShock. Close MultiShock, open %LocalAppData%\PiShock\MultiShock\Plugins\, and move the plugin's file or folder out of it.

Changes to a plugin's nodes don't appear after Reload. Restart MultiShock. Development reload updates pages and services, but the flow subsystem keeps its registered node types until a full restart. See packaging and testing.

Flows

A flow won't start.

• If the flow uses a plugin you don't have, its nodes show as "Unknown" and the flow can't start. Install the plugin, or delete those nodes.
• If a trigger can't start, the whole flow stops. Starting it from the Home page shows the reason, such as a keybind that couldn't be registered.
• Click the problems button in the flow editor's toolbar to see issues such as a missing trigger or setting.

A flow stopped by itself. Stop everything stops every flow and keeps them stopped, even after a restart. Start them again with Run.

A node has a red "!" badge. Its last run failed and its branch stopped there. Hover over the node to read the error. The badge clears the next time the node runs without an error.

An input is empty even though it's wired. Data only comes from nodes that already ran earlier in the same run. See how a flow runs.

Events arrive much later than expected. The default flow queue runs events one at a time. A slow request or long delay can build a backlog. Reproduce with Display nodes, check node timings, and review flow execution before increasing concurrency. Shocker cooldowns and device command queues can add a separate wait after a flow submits an action.

Keyboard shortcuts and keybinds

Ctrl+K, ?, and Shift+Esc are app shortcuts. MultiShock must have focus for them to work; Shift+Esc is not a global emergency-stop hotkey.

A flow's Keybind trigger can use a global registration. If the flow fails to start, check its reported registration error, choose another combination, and close conflicting registrations in other apps. Platform support differs; Linux global hotkeys require X11 or XWayland. A keybind failing to register is not fixed by repeatedly starting additional copies of MultiShock.

Slow or unresponsive automation

1. Stop output and reproduce with a minimal flow or plugin action.
2. Open Debug & diagnostics → Performance, turn on Capture performance, and click Reset capture to begin a short comparison.
3. Reproduce the issue. Capture remains enabled while you navigate elsewhere.
4. Return and click Prepare report for a copyable JSON report. Turn capture off when finished.

CPU and memory measurements describe the whole process. Operation timings include asynchronous waits and can overlap; they are not per-plugin CPU usage. Flow nodes and plugin initialization are measured automatically, while other background work appears only when instrumented. Include the reproduction and logs alongside the report rather than treating a long elapsed time as proof of the cause.

Running two copies

Only run one copy of MultiShock at a time. Two copies share the same settings and flows, so both would run your flows and send commands twice, and the second copy may fail to start. Close MultiShock from its window before starting another copy, for example a development build.

Updates

MultiShock checks for updates when it starts, if Check for updates on startup is on under Settings → General. It downloads updates in the background and shows "Update ready"; the update is installed the next time MultiShock restarts, so it may close and reopen right after starting. Restart now in Settings → General installs it straight away.

Choose between Stable (recommended) and Beta (bleeding edge) with Release track in the same place. Switching from Beta back to Stable can install an older version.

If updates never arrive, check the log for "Automatic update check failed". Also check that startup update checks are enabled and that you are using an installed Windows build. Unpackaged builds skip the updater; non-Windows targets do not use it. Update ready means downloaded, not already installed.

Start fresh

Settings → Advanced → Reset to defaults resets the main configuration and signs you out. The app attempts to keep the old settings as app-config.json.reset-backup in %LocalAppData%\PiShock\MultiShock\. Flows, installed plugins, plugin-configs/, and plugin-owned data are separate and remain in place. Restart MultiShock afterwards. Back up first: later resets overwrite the reset backup. See files and recovery.

Getting help

Ask in the PiShock Discord, in #multishock-discussion. Include:

• the version, from About this build on the Home page,
• Windows/OS version and whether this is an installed or development build,
• plugin versions if the issue involves plugins,
• what you did and what happened,
• the time of the failure and the matching log files,
• any Recent Plugin Errors, node error, or short performance capture.

Do not share configuration exports, configuration backups, or unredacted plugin data: they may contain sign-in tokens or integration secrets. Review logs, screenshots, reports, and flow settings for private values before sharing them. Do not post the whole app data folder. See what to keep private.

Contributors

Thank you to everyone who has helped improve this documentation.

bwmp