Diagnostics

When something doesn’t behave as expected, a diagnostics file shows what Layout saw and did. It’s a JSON file that you save on your Mac and attach to a bug report yourself. Nothing is sent anywhere.

Export diagnostics

1. Reproduce the problem.
2. Without quitting Layout, choose Export diagnostics…. It’s in three places:
   • the menu of the Layout icon in the menu bar, where it’s always available, even while Layout is paused or busy;
   • Settings › About;
   • the command palette.
3. Choose where to save the file. By default, it goes to your Desktop, named with the date and time, such as Layout-diagnostics-2026-09-23-143012.json.
4. Leave Include window titles off, unless the titles matter for your report (see below).
5. Click Export. Layout saves the file and shows it in the Finder.

Caution

Don’t quit Layout before exporting. The recent events live in memory only, so quitting erases them.

Layout reads its state at the moment you choose Export diagnostics…, before the save panel opens. Exporting only reads: it doesn’t scan windows again or move anything.

What the file contains

• Your setup: Layout’s version and build, your macOS version, your displays, whether Layout has the Accessibility permission, and whether AeroSpace is running.
• Layout’s state: whether it’s active or busy, whether a workspace or window request is waiting, and the last message it showed.
• Each workspace: its windows, and what switching to it would hide, show, or reposition, including a switch that macOS full screen would block.
• Each window: its workspace, zone, placements in the workspaces that share it, how recently you used it, and what the last Accessibility scan reported about it.
• Recovery and apps: the recovery journal, and the apps that are running.
• Your configuration, as saved: workspace names, apps, folders, and links. If configuration.json can’t be read, the file also includes its raw content.
• The last 300 events: workspace requests; switches that succeeded, were refused, or were canceled, with the reason; apps that came forward and took Layout to their window’s workspace; launches; pauses; and the messages Layout showed.
• Findings: a short list of anomalies to read first, such as apps configured in a workspace whose windows are all in another workspace.

Window titles

Window titles can name your documents, web pages, and conversations. By default, the export replaces each title with a stable alias, such as ‹Title 3 · 24 chars›, including inside messages and events. Document paths get an alias too. The same title always gets the same alias, so windows can still be followed through the file.

Turn on Include window titles to keep the real titles.

Your configuration is always included as it is, with your workspace names, folders, and links. Read the file before you share it if any of them are private.