Configuration troubleshooting

Multiboxer validates many references and values at startup. A configuration error normally prevents startup and reports the offending path or name.

JSON does not load

Check these first:

• Every property name and text value uses double quotes.
• Every entry except the last has a comma.
• The final item in an object or array has no trailing comma.
• Opening and closing braces and brackets match.
• Windows paths use doubled backslashes.
• There are no comments.

Valid path:

"executable": "C:\\Games\\MyGame\\Game.exe"

The wrong configuration opens

Without a command-line argument, Multiboxer first looks for:

%APPDATA%\MultiBoxer\config\default.json

If it is absent, the application tries to copy the installed config\default.json template there. In development or when copying fails, it may use the template beside the application. The Config button opens the file actually loaded for this run.

Main-region errors

main_region must:

• Be non-empty.
• Match a name in regions.
• Be initially owned by exactly one instances[].region entry.

Every instance must own an existing region, and two instances cannot initially own the same region.

A window launches in the wrong place

Verify:

• display is the correct zero-based monitor index written as a string.
• The region coordinates are relative to that display.
• Width and height are positive.
• Windows display scaling and physical monitor ordering match your assumptions.
• The instance references the intended region name.

An invalid or unavailable display value can fall back to monitor 0.

An executable does not launch

The configuration validator does not verify executable paths. Check that the file exists, the account can run it, and any working_directory is correct. Remember to double backslashes in JSON.

A key is rejected

Use a name from keys and actions. Combos must contain modifiers first and one ordinary key last:

Valid:    Ctrl+Shift+1
Invalid:  1+Ctrl
Invalid:  Ctrl+
Invalid:  Ctrl+Shift

The wildcard is any, not *.

A keymap does nothing

Check that:

• actions contains at least one outer step.
• Each step contains at least one action.
• The keymap is enabled.
• The trigger is in keys, or a UI/selection mechanism invokes its name.
• targets resolves to an active managed instance.
• Global forwarding has not been disabled.
• execute_on matches the edge you expect.

The required action shape is:

"actions": [
  [
    { "action": "forward" }
  ]
]

The double nesting represents steps and the actions within each step.

A target or keymap name is unknown

Instance, region, and keymap references are case-insensitive but must otherwise match configured names. Valid target selectors are only all, all_other, self, and explicit instance names.

Named keymap state actions and UI bindings require a keymap with name. Duplicate named keymaps fail validation.

Mouse broadcasting behaves unexpectedly

sync_mouse: true performs a one-time pointer synchronization before an action. It does not enable continuous broadcasting.

Use this for continuous broadcasting:

{
  "action": "mouse_broadcast",
  "mouse_broadcast_mode": "toggle"
}

The mode changes on trigger release. once and until_click stop at the next mouse button-down event.

Virtual-mouse injection fails

This is an advanced/internal feature. Start with:

"inject_virtual_mouse_dll": false

When enabled, Multiboxer must find compatible Injector32.exe and MouseVirtualizer32.dll helper files. Security software may quarantine them, and the target process must be compatible. Enable debug for more detail.

Capture compositor fails at startup

When capture_compositor.enabled is true:

• backend must be desktop_duplication_d3d11.
• fps must be between 1 and 240.
• stream_regions must retain at least one valid non-main region.
• Every stream name must exist.
• main_region cannot appear in the streams.

Compositor initialization failure is fatal to startup. Disable the compositor while testing the basic window layout.

A UI button is rejected

Button IDs must be non-empty and unique across ui.buttons and every keymaps[].ui_button. Coordinates cannot be negative, and dimensions must be greater than zero. A non-empty keymap binding must name an existing keymap.

Allowed roles are config and action. A keymap-owned ui_button requires the containing keymap to have a name.

Logging

Enable diagnostics temporarily:

"debug": true,
"debug_log_path": "logs\\multiboxer.log"

Relative log paths are resolved from the configuration file's directory. If no path is specified, logging uses:

%TEMP%\MultiBoxerLogs\multiboxer.log

Turn detailed logging off again after troubleshooting if you do not need it.

Safe way to isolate a problem

1. Start from the quick-start configuration.
2. Correct only the executable paths and confirm all five windows launch.
3. Confirm the regions before adding input mappings.
4. Add one keymap at a time.
5. Add swapping, wildcard forwarding, UI buttons, injection, or compositor capture last.