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.
A permission does not take
Section titled “A permission does not take”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.
- Click Reset Entry in TilingBud’s permission window.
- 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”.
Windows are not arranged
Section titled “Windows are not arranged”Find out why with the command line tool:
tilingbud query --windowIt 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
layoutin the space’s[[space]]entry and[tiling] layout. - A rule floats the app. Look in Settings › Apps, or run
tilingbud query --rules. A rule withfloat = falseforces 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 --alllists them with theirlevel. - 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.
A space switch is slow or does not arrive
Section titled “A space switch is slow or does not arrive”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.
Shortcuts do not fire
Section titled “Shortcuts do not fire”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+hfires 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_appsturns every shortcut off in the listed apps, andappsorexcept_appslimit 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.
The configuration file has an error
Section titled “The configuration file has an error”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.
Make a diagnostic report
Section titled “Make a diagnostic report”Install the command line tool with Install Command Line Tool… in TilingBud’s menu, then run:
tilingbud doctorThe 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.
Read the log
Section titled “Read the log”TilingBud writes to the system log. In Terminal:
/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>.