> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minimalmacropad.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot MinimalPad Studio for Mac

> Fix common MinimalPad Studio for Mac issues — the pad not being found, read-only mode, profiles not switching, and Bluetooth permission.

Work through the section that matches what you're seeing.

## Studio doesn't find my pad

<Steps>
  <Step title="Check the cable">
    A **charge-only** USB-C cable powers the pad but carries no data. If the underglow comes on but Studio never finds it, swap the cable. This is by far the most common cause.
  </Step>

  <Step title="Check nothing else has the pad">
    Only one app can hold the pad's USB port. Quit [Studio for browser](/browser/overview), any terminal or serial monitor, and any flashing tool, then try again.
  </Step>

  <Step title="Try another port, not a hub">
    Connect the pad directly to the Mac while troubleshooting.
  </Step>

  <Step title="Wake the pad">
    On battery, the pad goes into deep sleep after 12 hours. Press any key.
  </Step>
</Steps>

## Studio found it but won't let me edit

Studio stays **read-only** when it can't be certain which device it's talking to. It says which case applies:

* **More than one MinimalPad, or another ZMK keyboard, is connected.** Disconnect the extra hardware. Studio deliberately won't guess.
* **The pad's identity didn't match.** Unplug it, plug it back in, and let Studio verify it again.
* **A reconnect failed.** Studio keeps showing your last known layout but won't write to it. Use **Try again**.

## Bluetooth isn't working

<Steps>
  <Step title="Check the permission">
    Open **System Settings › Privacy & Security › Bluetooth** and make sure MinimalPad Studio is allowed. If you dismissed the prompt on first launch, this is where to fix it.
  </Step>

  <Step title="Pair the pad first">
    Studio doesn't pair the pad for you. Pair it in **System Settings › Bluetooth** like any keyboard, and wait until macOS shows it as connected.
  </Step>

  <Step title="Check the pad's Bluetooth profile">
    The pad advertises only when its selected profile has nothing paired to it. See [Bluetooth profiles](/configure/bluetooth-profiles) to switch to an unused slot or clear one.
  </Step>

  <Step title="Wake it if macOS shows it greyed out">
    A greyed-out pad in **System Settings › Bluetooth** is paired but not connected, and **Connect** there usually does nothing. Press a key on the pad: it reconnects itself within a few seconds. See [Bluetooth problems](/help/bluetooth).
  </Step>
</Steps>

More in [Bluetooth problems](/help/bluetooth).

## Profiles aren't switching

<AccordionGroup>
  <Accordion title="The sidebar says Update needed" icon="microchip">
    App profiles need firmware **0.3.0 or newer**. Studio carries the firmware and can install it — see [Updates](/mac/updates).
  </Accordion>

  <Accordion title="The menu bar says Switching paused" icon="pause">
    You paused switching. Click the menu bar icon and choose **Resume**. The pause lasts through reconnects until you resume or quit.
  </Accordion>

  <Accordion title="The pad is typing into another computer" icon="display">
    Profiles only switch on the computer the pad is currently sending keys to. If you moved the pad to another host over Bluetooth, your Mac's profiles pause until you switch the pad's output back — use the **Use USB** / **Use Bluetooth** keys, or a profile key on the Connections & LEDs layer.
  </Accordion>

  <Accordion title="A profile says Needs repair" icon="wrench">
    Its layer was renamed, removed, or reordered — often by editing the pad in the browser configurator, or by an interruption while the profile was being created. Studio never switches to an unhealthy profile. Accept the repair it offers, or delete the profile and make it again. See [Layers](/mac/layers).
  </Accordion>

  <Accordion title="The menu bar says Unavailable" icon="plug-circle-xmark">
    The pad's profile channel isn't open. Check the connection first; if the pad is connected and this persists, the firmware may not have the host channel — see [Updates](/mac/updates).
  </Accordion>
</AccordionGroup>

## An Open app key does nothing

* **Studio for Mac isn't running.** The pad only reports the key; Studio opens the app. Start Studio — it can stay in the menu bar with the window closed. Turn on **Open at login** so it's always there.
* **The firmware is older than 0.5.0.** The **Open app** tile doesn't appear in the inspector on older firmware, and a key set on another Mac does nothing. The sidebar footer says **Update available** — see [Updates](/mac/updates).
* **The pad is typing into another computer.** Like profiles, Open app keys only work on the computer the pad is sending its keys to.

## The pad shows as connected but nothing gets through

Over Bluetooth, a pad on firmware older than **0.4.2** could show as connected after your Mac reconnected to it — after a restart, Bluetooth off and on, or waking from sleep — while no key, dial turn, or edit got through until the pad itself was restarted. Update the firmware from [Studio for Mac](/mac/updates); you don't need to pair the pad again.

Don't forget the pad in **System Settings › Bluetooth** for this. It never helped, and it can leave a pad that shows up nearby and won't pair. If you already did, the pad still remembers your Mac: hold the bottom-right key, press the Bluetooth device key for this Mac, press **Clear profile** (the second key on the second row), and pair again.

## The profile colour isn't showing on the pad

* **The lights are off.** A profile colour overrides the colour of lights that are already on; it won't switch them on. Press the lighting toggle on the **Connections & LEDs** layer.
* **The lights went to sleep.** After 30 seconds idle they fade out. Press a key or turn the dial.
* **The firmware doesn't advertise LED control.** Studio still switches the layer, just without colour. Update the firmware.

Remember that the colour square in Studio is what Studio is asking for, not a reading from the LEDs.

## Changes didn't save

Studio writes to the pad about three seconds after each change and waits for the pad to confirm before quitting. Edits are only at risk if you **force-quit** Studio or pull the cable within those few seconds.

If a save fails, Studio stays open and offers **Try again**. Take it — choosing **Quit Without Saving** discards that work.

See also [Changes didn't stick](/help/changes-not-saved).

## Still stuck?

Check [Limits and known issues](/mac/limits) first — some behaviour is expected in this release.

Otherwise, email [minimalpad@unbox-studio.com](mailto:minimalpad@unbox-studio.com) with:

* what you were doing when it went wrong
* your macOS version
* the firmware version from Studio's sidebar footer