# Notification troubleshooting

Solo sends both [in-app toasts](../notifications/in-app-toasts.md) and native desktop notifications depending on the situation. If notifications aren't showing up, work through these checks in order.

## Check 1: Verify Solo's notification status

1. Open **Settings** > **Notifications**. By default, press `Cmd+,` on macOS or `Ctrl+,` on Windows/Linux; this shortcut can be changed in **Settings** > **Hotkeys**.
2. Check the **System notifications** status:
   - **Enabled** — on macOS, Solo has notification authorization. On Windows, Solo reports Enabled without checking Windows notification settings, so verify Windows settings separately if delivery fails.
   - **Denied** — macOS has denied permission. Click **Open system settings**.
   - **Not requested** — macOS has not reported a permission decision. Click **Enable notifications** to request permission.
   - **Provisional** — macOS granted provisional delivery. Click **Open system settings** to review Solo's notification settings.
   - **Ephemeral** — macOS reported ephemeral authorization. Click **Open system settings** to review Solo's notification settings.
   - **Unavailable** — Solo could not access its native notification subsystem. Relaunch Solo; if the status remains Unavailable, report the issue.

## Check 2: System permissions

On macOS, follow the steps below when the status is **Denied**, **Provisional**, or **Ephemeral**. On Windows, check the host settings whenever native delivery fails; Solo's **Enabled** status does not inspect Windows notification settings.

On macOS:

1. Go to **System Settings > Notifications** (or System Preferences on older macOS).
2. Find **Solo** in the app list.
3. Turn on **Allow notifications**.

On Windows:

1. Go to **Settings > System > Notifications**.
2. Make sure notifications are enabled.
3. Find **Solo** in the app notification list and allow notifications.

If Solo does not appear in the macOS list and the status is **Not requested**, click **Enable notifications** in Solo's Notification settings to request [permission](../notifications/macos-permissions.md). That button requests macOS permission only; on Windows, use Windows notification settings.

## Check 3: Focus or do-not-disturb mode

Focus modes and do-not-disturb settings can silently suppress notifications from all or specific apps.

On macOS:

1. Check the **Control Center** or **Focus** menu to see if a Focus mode is active.
2. If one is active, add Solo as an allowed app:
   - Go to **System Settings > Focus > [Your Focus Mode] > Allowed Notifications > Apps**.
   - Add **Solo**.

On Windows:

1. Open **Settings > System > Notifications**.
2. Check **Do not disturb** and notification priority settings.
3. Add Solo as an allowed app if do-not-disturb mode is enabled.

## Check 4: Send a test notification

In **Settings** > **Notifications**, click **Send test**.

- If you see the test, the explicit native test path reached a visible notification. A missing process or terminal alert can still be caused by its notification level, focus-aware route, selected-process suppression, or event input.
- If you do not see the test, the result does not isolate one cause. Recheck Solo's status, Focus/Do Not Disturb, and the operating system's per-app presentation settings.

## Check 5: Understand focus-aware delivery

For normal process-crash, terminal, auto-restart-exhaustion, and `solo.yml` alerts:

- When Solo is focused, the alert appears as an in-app toast.
- When Solo is not focused, the alert is sent as a native notification.
- A terminal alert from the selected process is suppressed while Solo is focused.
- A successful auto-restart remains a transient in-app toast even while Solo is unfocused.

**Send test** explicitly uses the native channel, and server announcements remain persistent in-app toasts. If you're always looking at the process when events happen, you'll generally get toasts instead of system notifications. That's expected behavior.

## Check 6: Notification levels

Project and process notification levels are combined by taking the more restrictive setting:

- **All** allows [terminal BEL/OSC alerts](../notifications/triggering-from-scripts.md) and important process alerts.
- **Important** allows crashes and auto-restart-exhausted alerts, but suppresses terminal BEL/OSC alerts.
- **None** suppresses both terminal alerts and important process alerts.

If a script notification is not appearing, confirm both the project and process allow **All**.

## Check 7: Rate limiting

Terminal notifications are rate-limited to 5 notifications per 10 seconds per process reader. Auto-restart is also rate-limited: after 10 restarts in 60 seconds, Solo stops retrying and writes an **[Auto-restart paused](../notifications/auto-restart-notifications.md)** banner in the terminal. The separate exhausted UI indicator and notification appear only when the effective notification level is **Important** or **All**; at **None**, Solo does not set or send them.

## Check 8: Verify OS notification settings

Even with permission granted, per-app OS settings can prevent visible presentation.

**macOS:**

1. Open **System Settings** > **Notifications** > **Solo**.
2. Verify **Allow notifications** is on.
3. Set alert style to **Banners** or **Alerts**.
4. Enable **Show in Notification Center**.
5. Enable **Show on Lock Screen** if needed.

**Windows:**

1. Open **Settings** > **System** > **Notifications**.
2. Find Solo and make sure notifications are on.
3. Expand Solo's settings and verify banners are enabled.
4. Check that Solo is not in any priority-only exclusion list.

Solo requests silent native notification content on macOS and Windows. For audible terminal, crash, and auto-restart-exhaustion alerts on macOS, choose a separate **Bell sound** in Solo's Notification settings. Solo currently has no corresponding Windows bell-playback branch, so Windows notification-sound settings do not enable Solo alert audio.

## Still not working?

- Fully quit and relaunch Solo. Notification initialization happens at startup.
- On macOS, try signing out and back in to refresh the notification subsystem.
- Report the issue via the [command palette](../command-palette/using.md) and choose **Report an issue or share feedback**. Solo automatically includes the app version, operating system, and OS version; include the notification event types you're testing and any unusual build or environment details that are relevant.

---

Are you a human? Read this doc on the web: https://soloterm.com/docs/troubleshooting/notifications