Skip to content
EN
Download

Troubleshooting

Start with Settings › Permissions & Features. It lists every permission TilingBud needs and which of its features work on this Mac, with the reason when one does not.

macOS ties a permission to the app’s signature, not to its name. If Accessibility is switched on in System Settings but TilingBud still asks for it, the entry belongs to an earlier copy of the app.

  1. Click Reset Entry in TilingBud’s permission window.
  2. Click Request Access and switch TilingBud on in System Settings › Privacy & Security › Accessibility. On newer macOS versions that page is called “Device Control and Data Access”.

Find out why with the command line tool:

Terminal window
tilingbud query --window

It shows what TilingBud sees of the focused window, the rules that match it and the reason it is tiled or not, for example floats: a window rule says float = true. Common reasons:

  • The space’s layout is off. Click the layout symbol on the control bar and choose a layout, or check layout in the space’s [[space]] entry and [tiling] layout.
  • A rule floats the app. Look in Settings › Apps, or run tilingbud query --rules. A rule with float = false forces tiling.
  • The window floats on its own. Dialogs, sheets and panels float. So do windows whose size the app does not let others set.
  • You floated it. ⌥ T or “Float Window” takes a window out until it closes. Press ⌥ T again to put it back.
  • The window is on another level. Some apps put windows above or below normal windows. TilingBud leaves them alone; tilingbud query --windows --all lists them with their level.
  • The window was open before TilingBud started. Rules act when a window appears. Choose Apply Window Rules Now, or run tilingbud rules --apply.
  • macOS placed it. A window placed with the green button or Window › Move & Resize goes back to its place on a space with a layout. Float it first.

TilingBud switches spaces the way the trackpad swipe does, so the switch slides. It cannot switch without the slide.

  • On a busy Mac the Dock can show the new space late. TilingBud waits up to three seconds more before it reports a failure, and a second key press during a slow switch starts once the first one is done.
  • After three switches in a row that did not arrive, TilingBud shows a notice. It names a process that uses a lot of CPU, with a button to quit it when macOS restarts it by itself, offers to restart the Dock, and links to the “Switch to Desktop N” shortcuts when they are off.
  • Turn on the “Switch to Desktop N” shortcuts in System Settings › Keyboard › Keyboard Shortcuts › Mission Control. TilingBud uses them when the swipe does not work.
  • Turn off “Automatically rearrange Spaces based on most recent use” in System Settings › Desktop & Dock. Otherwise space numbers change by use, and shortcuts, names and rules point at other spaces. Settings › Permissions & Features lists it as recommended.

Open Settings › Shortcuts. It marks keys that an enabled macOS shortcut also uses, and shows “Not active: macOS or another app holds these keys” for keys that could not be registered. Choose other keys, or turn off the other shortcut.

  • The wrong side. lalt+h fires only with the left Option key. The recommended set uses the left Option key, so the right one still types special characters.
  • A mode is on. While a mode is on, only its shortcuts work. The control bar shows the mode; Escape leaves it.
  • The app is excluded. exclude_apps turns every shortcut off in the listed apps, and apps or except_apps limit a single shortcut.
  • Media keys or a capturing mode. These need Input Monitoring in Privacy & Security. Settings › Shortcuts says when it is missing.
  • Caps Lock as Control. The shortcuts on Control are made for Caps Lock as Control ([keyboard] caps_lock_control_escape). Settings › Keyboard says when macOS’s Modifier Keys setting or another tool such as Hammerspoon or Karabiner changes these keys too.

Settings › Configuration File shows the status of the file and each problem with its line number. A mistake in one line does not stop the rest of the file from applying. A shortcut or rule with an error is reported with its line, and the others keep working.

After an edit outside Settings, the file reloads when you save it. tilingbud config --reload reads it again by hand.

Install the command line tool with Install Command Line Tool… in TilingBud’s menu, then run:

Terminal window
tilingbud doctor

The report lists TilingBud’s version, the macOS version and build, the SIP state, the macOS builds the release was tested on, whether each feature works with a short code, the problems of the configuration file and how fast TilingBud reacted to the latest events. Attach it to your support request.

TilingBud writes to the system log. In Terminal:

Terminal window
/usr/bin/log show --last 5m --info --predicate 'process == "TilingBud"'

--last 5m covers the last five minutes; macOS keeps these lines only for a short time, so run it soon after the problem. Window titles, file paths and typed text show as <private>.