Troubleshooting

My mappings do nothing (buttons press but nothing happens on the Mac)

1. Check the Accessibility permission: System Settings > Privacy & Security > Accessibility. Controllers must be listed and enabled. After granting it, quit and reopen the app.
2. Check the On/Off toggle at the top-left of the main window; it must be On.
3. Select the controller in the left pane and confirm a layout is assigned to it (the row says "Layout: …", not "Layout: None").
4. Confirm the buttons you are pressing actually have bindings in that layout.
5. If another app that remaps input (keyboard remappers, other controller mappers) is running, quit it and test again; input-simulation apps can conflict.

My controller doesn't show up in the device list

1. Confirm the controller is powered on and in range.
2. For Bluetooth: open the in-app connect panel (Bluetooth button, bottom-left), put the controller in pairing mode, and click Connect when it appears. Pairing mode is usually a dedicated sync button, or a button combo (e.g. PS + Share on DualShock 4, or PS + Create on DualSense).
3. Test with a USB cable. If it works wired but not wireless, the issue is pairing; forget the controller in macOS Bluetooth Settings and pair again.
4. Nintendo Switch 2 controllers do not appear in macOS Bluetooth Settings; pair them in the app's connect panel only.
5. Switch 1 Joy-Cons and Pro Controller take input over Bluetooth only; USB is just for charging.
6. Very old or exotic controllers (PS1/PS2, original Xbox, Xbox 360 wireless) need a third-party USB adapter.

A Switch 2 controller (Pro 2, Joy-Con 2, GameCube) won't pair

1. macOS Bluetooth Settings cannot see Switch 2 controllers at all; this is normal. Use the app's connect panel.
2. Open the connect panel and hold the controller's sync button (next to the USB port on the Pro Controller 2, on the rail of a Joy-Con 2) until the player lights sweep back and forth.
3. Click Connect when it appears in the panel. Stay in pairing mode until it connects.
4. After the first pairing, the controller reconnects automatically whenever it's powered on.
5. If the controller was re-synced to a Switch console in between, pair it in the app again.

A DualShock 3 / Sixaxis won't connect

The DualShock 3 doesn't pair through normal Bluetooth scanning. Connect it with a USB cable and press the PS button. For Bluetooth use afterward: connect by USB once, press the PS button, then unplug; if a pairing code is requested, enter 0000.

My game sees double inputs (controller AND the mapped keys)

The game is reading the controller directly while Controllers also sends the mapped output. Select the controller and click the lock button (bottom-left) to make it Exclusive; that hides the controller from other apps so only the mapped output reaches the game. Turn Exclusive off again for games that should see the controller natively.

My game stopped seeing the controller entirely

The controller is probably set to Exclusive (a lock symbol shows on its connection line). Select it and click the lock button to make it Shared again.

The gyro cursor drifts or doesn't respond

1. Confirm the binding: a button must be bound to Motion Sensor Cursor (or Scroll), and motion is only active while that button is held (hold mode) or after pressing it (toggle mode); check the mode in Settings > Motion.
2. Motion is supported on DualSense, DualShock 4, Switch 1 Joy-Cons/Pro, and Switch 2 controllers. Other controllers don't expose a gyro.
3. Small drift: hold the controller still for a second or two; the app auto-calibrates each controller's rest bias.
4. If motion is dead on a Switch 1 controller, power it off and back on so it reconnects; the app re-enables the gyro on connect and recovers automatically if the controller ignored the first attempt.
5. Adjust sensitivity and dead zone in Settings > Motion.

No battery percentage is shown

• USB-connected controllers never show battery (cable-powered); this is intentional.
• A reading can take up to ~10 seconds to appear after connecting.
• DualShock 3, wired-only controllers, and most generic gamepads don't report battery at all.
• Some MFi controllers don't report battery to macOS.

The battery percentage looks off

• Switch 1 controllers only report coarse steps (roughly full / medium / low / critical), shown as approximate percentages.
• Switch 2 levels are estimated from battery voltage, so treat them as a good estimate rather than an exact gauge.
• With two identical Xbox controllers connected, the two readings are real but which row shows which can occasionally swap; a macOS limitation in matching the radio device to the input device.

My layout doesn't load when the controller reconnects

The app reapplies the last layout used with each controller automatically. If it doesn't: select the controller and click the layout once to assign it again. Layouts are scoped per controller model and player slot; if you use several identical controllers, each player slot keeps its own assignment.

Vibration / rumble doesn't work

Controllers maps input only (digital buttons, axis buttons, hat switches). It does not control rumble, LEDs, or audio on the controller.

My controller turns itself off after a while

Wireless controllers sleep after inactivity. Enable Keep Controllers Awake in Settings. Note that some controllers, notably the DualSense, may still sleep on macOS regardless of this setting.

Buttons panel shows nothing useful for my generic gamepad

Generic HID gamepads vary. The app shows whatever digital buttons, axes, and hat switches the controller reports. If a control doesn't appear there, it can't be mapped.

Contact support

Email hello@vividmachine.com with your macOS version, Controllers version, controller model, USB or Bluetooth connection, and the steps that reproduce the issue.