Troubleshooting
Most problems come down to a plugin that is waiting for approval, a missing permission, or an error in the plugin's code. The log tells you which.
Read the log
Macotron writes to the macOS unified log under the subsystem io.statico.macotron. Plugin output has the category plugin, and each line carries the plugin's file name.
Follow plugin output live in Terminal while you reproduce the problem:
log stream --level info --style compact --predicate 'subsystem == "io.statico.macotron" AND category == "plugin"'Look at the last ten minutes, from the host as well as plugins:
log show --info --last 10m --style compact --predicate 'subsystem == "io.statico.macotron"'Keep --level info and --info. Without them, log drops ordinary console.log lines and shows only warnings and errors.
A coding agent can run these commands too. Ask it to read the log when a plugin it wrote misbehaves.
A plugin does nothing
If a plugin logs nothing at all, it never ran. Open its page in Settings → Plugins and look for one of these:
- "This plugin is new" or "The source file changed" (orange). It waits for your approval. Select Review & Load or Review & Reload. See Security.
- "This plugin is disabled". Turn on Enabled.
- A red error box. The plugin failed to load, and the box shows the error. Fix the code, or ask your agent to.
- "Needs Macotron API …". The plugin asks for a newer Macotron. Update the app; see Updates.
To see the load error from Terminal, check the file:
/Applications/Macotron.app/Contents/MacOS/Macotron --check plugins/my-plugin.jsI saved a change and nothing happened
With Hot Reload off, a saved change does not run until you approve it. Select Review & Reload in the Macotron menu, or turn on Enable Hot Reloading while you work on the plugin.
A hotkey does not fire
- Check Settings → Permissions. Hotkeys that watch the keyboard need Input Monitoring, and window hotkeys need Accessibility.
- Look for a conflict warning under the shortcut in Settings. Two plugins, or a plugin and the launcher, can claim the same combination. Plugins with a conflict are marked in the Plugins list.
- Another app may hold the combination already. Record a different one in Settings → Plugins.
Hotkeys has more.
A menu bar item is missing
macOS hides items it has no room for, which often happens on a Mac with a notch. It also hides an item you Command-dragged out of the menu bar. The plugin's page in Settings → Plugins → Menu Bar says which, and Restore puts back a removed item. Make room by removing other items, or by moving some into Control Center in System Settings. See Menu bar.
A menu bar item shows old or placeholder data
The plugin's refresh probably threw an error, and the item kept what it last drew. Read the log for the plugin. When you write plugins, catch errors and draw a failure state; see Async code and errors.
A permission will not turn green
Quit and reopen Macotron. If that does not help, remove Macotron from the list in System Settings → Privacy & Security and grant it again. See Permissions.
Badges on the menu bar icon
| Badge | Meaning |
|---|---|
| Red dot | A permission is missing. The top of the Macotron menu names it. |
| Orange dot | Plugin files changed and wait for review. |
| Orange reload arrows | Hot Reload is on. |
| Blue down arrow | Plugin updates are available. |
Hold the pointer over the icon to see the reason as a tooltip.
I deleted a plugin by mistake
Deleting a plugin from Settings keeps a copy in the workdir's backups/ folder, with the date in its name. Move it back into plugins/ and approve it.
Report a bug
File an issue at github.com/statico/macotron/issues. Include your macOS version, the Macotron version from Settings → General, and the relevant lines from log show. Remove anything private from the log first.