Troubleshooting

Common symptoms and where to fix them. Each guide’s own “Pitfalls” section has the full detail; this page is the symptom-first index into them.

Nothing appears when I launch

OpenNook runs as a menu-bar accessory app - there is no Dock icon and no window on launch, by design. Press ⌥⌘; or click the menu-bar item to expand the nook. (See Your first nook.)

The chrome is blank or wrong on a Mac with no notch

The default presentation is .auto, which renders a free-floating panel on a display with no notch. If you forced .notch, the eared shape hangs off a bare menu bar and can look wrong. Set the Settings “Layout” picker back to Auto or Floating. (See Displays and presentation.)

The global hotkey does nothing

Another app may already own ⌥⌘;. A failed registration is surfaced in Settings as a per-shortcut warning (HotkeyRegistrationFailure); rebind to a free combination there. (See Your first nook.)

Text or icons render in the wrong color (white on white)

The notch panel’s SwiftUI colorScheme is unreliable, so adaptive colors like Color.primary resolve for the wrong appearance. Build your palette from explicit Color.white / Color.black at a fixed opacity. (See Theming.)

The Settings gear is missing

topBar.showsSettings = false removes the gear, and topBar.showsTopBar = false removes the whole bar (gear included). Settings stays reachable from the menu-bar fallback unless showsSettings is off. (See Settings chrome.)

The file shelf is empty after a relaunch

Under the App Sandbox a lost security-scoped grant can make the shelf look empty; the store deliberately preserves non-resolvable items rather than deleting them. Use acceptanceMode: .strict if you would rather a drop fail at drop time than fail to survive a relaunch. (See File shelf.)

A queued activity never shows

The activity queue yields to the user: while you are hovering or have the nook open, it waits. A background module’s activity is also gated unless its priority is .high. (See Activity queue.)

Registering modules traps at launch

A duplicate module id, or an empty NookHostConfiguration, traps on purpose - both are main.swift setup bugs. Give every module a unique id, and register at least one. (See Multiple modules.)