Troubleshooting

Run this first, whatever the symptom. It is four lines and it rules out half the list.

$ mdctl status
version: 0.1.0
state: active
active group: Office
groups: Home, Office, MacBook Air 13-inch (M1)

mdctl says the app is not running

$ mdctl status
mdctl: MoreDisplays is not running

Exit code 3. The tool is a client and there was nobody on the socket. Either the app is not running, or it is running and has not opened the socket yet.

$ ls -l ~/Library/Application Support/MoreDisplays/mdctl.sock
ls: ~/Library/Application Support/MoreDisplays/mdctl.sock: No such file or directory

If the app is open and the socket is missing, the launch sequence did not finish. Quit and reopen it, then check again.

If a script hits this at login, it is a race: the script reached the socket before the app opened it. Wait for it rather than failing; the recipes page has the loop.

No virtual display is created

Two causes, in order of likelihood.

The kill switch is off. Allow virtual displays in Settings stops every creation and releases anything that exists. It is deliberate and it is silent, which is exactly why it is the first thing to check.

The interface is unavailable on this Mac. Settings says so, in one sentence with the reason: Virtual displays are unavailable on this Mac. Below macOS 14 the app declines rather than guessing; on a newer macOS the private interface may simply have changed shape.

This is the failure mode the whole design expects. Nothing else in the app stops working; the window still opens, the groups are still there, and the feature reports itself unavailable.

The client connects to a black screen

The display exists and nothing is being composited to it. In order of likelihood:

The client attached before the display existed. Common right after a login. Disconnect and reconnect the client.

Nobody is logged in. The app runs in your user session. Before you log in there is no app and therefore no virtual display, whatever the group says. Log in over SSH first, or use automatic login.

The session is on a different display. Check which display the group makes main, and whether the group includes physical displays that might be taking the session instead.

The mode is something the client cannot decode. Drop the group to 1920 by 1080 at 60 Hz with HiDPI off. If the picture comes back, work upward from there.

The resolution keeps changing back

Something else is asking for it. Jump Desktop and Parsec both request a display resolution when they connect, and both do it again when the link changes.

Turn off automatic or dynamic resolution in the client. Remote clients says where the setting is.

Marking the display protected in its group makes the app put the arrangement back, but it concedes after five restores in twenty seconds. Protection is not a way to win an argument with a client that asks on every reconnect.

The group did not come back after a restart

Three things have to line up, and it is usually the first.

1. The app has to be running. Open at login in Settings. If macOS refused the login item, Settings says macOS refused to open MoreDisplays at login.
2. The group has to be marked to activate on launch.
3. Virtual displays have to be allowed. The kill switch again.

$ mdctl status
version: 0.1.0
state: idle
active group: (none)
groups: Home, Office

state: idle with groups listed means the app launched and activated nothing, which points at 2 or 3.

A keyboard shortcut does nothing

Another app already owns the combination. The group still saved; Settings lists the conflict.

Pick a different combination, or quit whatever owns it. macOS gives a shortcut to whichever process registered it first, and there is no way for a second one to win.

Sync says it is unavailable

Sharing the library needs an entitlement, a signed build and a signed-in iCloud account. Settings names which of the three is missing.

A build you compiled yourself will always report this, because the entitlement counts only when the bundle embeds a provisioning profile granting it. Everything else keeps working against the local file. Sync and backups has the detail.

Brightness keys do nothing

The feature needs accessibility permission, and it is off by default. Turn it on in Settings and grant the permission there.

If it is on and granted and the keys still do nothing, the display under the pointer may have no lever to pull: a virtual display has no DDC channel, and the gamma fallback does nothing visible on some Apple silicon. Brightness has the table.

Spaces switching behaves oddly

On macOS 26, a virtual display in the hierarchy can interfere with Spaces focus and Space switching, so switching Spaces sometimes moves focus to the wrong display.

This is macOS behaviour, and any workaround would mean fighting the window server for control of focus, which produces a worse result than the original problem. Fewer displays makes it less frequent.

Nothing here helped

Settings has Export Support Bundle, which writes a zip you can attach to an issue. It contains the configuration, the app’s own log entries from the last day, and the display topology, and nothing from outside those three places.

$ unzip -l ~/Desktop/MoreDisplays-support.zip
  Length   Name
-------  ----
   4821  manifest.json
  18240  config.json
  96114  log.txt
   2903  topology.json

Open it before you send it. It is a zip of plain files, and reading what you are about to attach takes a few seconds. Then file an issue.

Next

• Support for where to send it.
• Uninstall if you are done with it.