Troubleshooting

Most problems come from a macOS setting or a missing permission, and Spacetile can check those for you. Start with the checks below, then find what you’re seeing in the sections after them.

Start here: run the checks

Click Spacetile’s menu-bar item. The line under Spacetile says what it’s doing; “Tiling windows as they open” means all is well.
Open Settings → Permissions. Any check that needs attention has an orange icon and an Open Settings button.
Click Open Settings next to each one, change the setting, then click Check Again.

Check	Should be	Why
Accessibility permission	On	Spacetile needs it to see, move, resize and focus other apps’ windows
Automatically rearrange Spaces	Off	Otherwise macOS reorders your Spaces, and switching by number lands on the wrong one
Stage Manager	Off	Stage Manager moves windows itself and fights tiling
Drag windows to edges to tile	Off	macOS’s edge-drag preview competes with Spacetile’s drop zones. The rest of macOS tiling works with Spacetile
Trackpad swipe between Spaces	On	macOS 27 only accepts Spacetile’s instant switching with this gesture on
Spaces	More than one	Spacetile can’t create Spaces; add them in Mission Control (`⌃↑`, then +)

Click the item. The panel says which of these it is:

The panel says	What to do
Needs Accessibility permission, with Grant Accessibility…	Click Grant Accessibility… and turn on Spacetile in the list. Spacetile restarts by itself once it’s on
An error from `config.json`	Click it to open the file and fix it, or use Revert to Last Good in Settings. Spacetile keeps the last good settings meanwhile. See If config.json has an error
Trial over: windows stay put until a Licence key is entered	Buy a Licence, then enter the key
Licence key not valid	Enter the key again from your Licence email, or use its activation link
Licence revoked	The Licence was refunded or withdrawn. Enter another Licence key
Update window ended before this version: renew to use it	Renew your Licence, or reinstall a version from inside your update window

A pause badge (instead of ⚠︎) means tiling is paused: turn the Tiling switch back on in the panel.

Windows don’t tile

What you see	Cause	Fix
Nothing tiles at all	Tiling is paused, Accessibility is off, or a Licence is needed	Check the menu-bar panel, as above
One app’s windows never tile	The app is in Always float, or isn’t a regular app (menu-bar apps and utilities are ignored)	Remove it in Settings → Rules. By default, Activity Monitor, App Store, Archive Utility, Calculator, Dictionary, FaceTime, Photo Booth, Screen Sharing, Software Update, System Information and System Settings float
One window doesn’t tile	It’s floating, or it’s a dialog, panel, or a window that can’t be resized	Focus it and press `⌥f` to tile it. Dialogs and fixed-size windows always float
A Space doesn’t tile	Its layout is Stack or Float	Press `⌥d` on that Space to tile it. Changing the layout in Settings only affects Spaces laid out afterwards
A rule doesn’t apply	Rules only affect windows opened after the change, and match the app’s menu-bar name	Reopen the window, or press `⌥f`. Check the name has no ? next to it in Settings → Rules
A window overlaps or sits in a stack	The app won’t shrink that small, so Spacetile stacked it	See Stack on overflow. Use fewer windows on that Space, a bigger display, or float the window

Switching Spaces is slow or goes to the wrong Space

It slides instead of switching instantly. Turn on System Settings → Trackpad → More Gestures → Swipe between full-screen applications (three or four fingers). When an instant switch fails, Spacetile falls back to ⌃← and ⌃→, which animate.
It lands on the wrong Space. Turn off Automatically rearrange Spaces based on most recent use in System Settings → Desktop & Dock. Also remember that full-screen apps count: ⌥N goes to the Nth Space in Mission Control, including full-screen ones.
It switches, then jumps to another Space. With “When switching to an application, switch to a Space with open windows” on, arriving on an empty Desktop can make macOS jump to another app’s Space. Spacetile switches back after its own switches; swipes and ⌃→ can still bounce. Turn that setting off in Desktop & Dock if it bothers you.
⌥N does nothing. That Space doesn’t exist yet. Add Spaces in Mission Control (⌃↑, then +).

A shortcut doesn’t work

What you see	Fix
⚠︎ next to the shortcut in Settings → Keys	Another app already owns that shortcut. Change it in one of the two apps
No shortcuts work	Use Spacetile’s shortcuts is off in Settings → Keys, or tiling is paused (only Pause works then)
Option shortcuts type special characters instead	Spacetile isn’t running or tiling is paused. Check the menu-bar item
Settings refuses a shortcut	`⌃←`, `⌃→`, `⌃↑`, `⌃↓`, `⌘Q`, `⌘Tab` and `⌘Space` belong to macOS. Choose another

A profile doesn’t apply as expected

What you see	Fix
“Profile couldn’t place N Spaces”	The profile uses Desktops you don’t have. Add them in Mission Control (`⌃↑`, then +) and apply it again
A tile stays empty	The app is still launching, or its window is on a Space Spacetile hasn’t shown since it started. It fills when the window appears
A Desktop wasn’t arranged	Visit each Desktop before capturing, so Spacetile has laid it out. Or design that Desktop in the Profiles window
It doesn’t apply when you connect a display	Turn on Apply automatically in the designer. It only applies when exactly the recorded displays are connected, in the same “Displays have separate Spaces” mode
“name didn’t load”	The profile file has a JSON error. Click it to open the file and fix it
The Focus filter applies the wrong profile, or none	The filter remembers profiles by name. After renaming a profile, choose it again in the filter

The spacetile command does nothing

Make sure Spacetile is running. The command sends instructions to the running app and doesn’t start it.
Check the command is installed: command -v spacetile should print /usr/local/bin/spacetile. See Check the command.
Check the spelling. Unknown commands are ignored silently. Compare with the Commands tables.
Install Command… says something already exists there. See If something is already at /usr/local/bin/spacetile.

Reset Spacetile

Settings: in Settings, use Restore Defaults on a pane, or quit Spacetile and delete ~/.config/spacetile/config.json. Spacetile writes fresh defaults when it starts.
Accessibility: if Spacetile is listed but still can’t move windows, remove it from System Settings → Privacy & Security → Accessibility with −, or run tccutil reset Accessibility com.kodehort.spacetile. Then open Spacetile and grant it again.
Everything: delete ~/.config/spacetile to remove your settings and profiles too.

Don’t delete Spacetile’s keychain items: they hold your Licence key.

Collect logs for a bug report

Spacetile logs what it does to the macOS unified log. To see the last five minutes, run this in Terminal:

log show --last 5m --predicate 'subsystem == "com.kodehort.spacetile"' --style compact

To watch it live while you reproduce the problem, use log stream with the same --predicate. Include the relevant lines, your macOS version and your Spacetile version (Settings → General → Updates) when you open an issue.