Troubleshooting

This page covers the most common issues when first using Kumo. If the problem is not listed here, try the FAQ or open an issue on GitHub.

Kumo does not start

Press Start in the Overview, and the status flips back to Stopped a moment later.

Common causes:

Kumo cannot find a Mihomo binary. Open Settings → Core, click Install managed core, and try again.
The mixed port (the local port Kumo proxies through) is already in use by another app. Quit that app, or change the port in Settings → Core.

If neither helps, check the Logs destination in the sidebar. The first red line is usually the real reason.

System Proxy keeps turning off

Toggle System Proxy on, and it snaps back to off with an error.

Two main causes:

The proxy is not ready yet. Kumo checks that the local port is accepting connections before enabling system proxy. If it is not, the toggle refuses. Wait a few seconds after Start and try again.
macOS reports a different active network than the one Kumo is trying to change. Open Settings → System Proxy in Kumo and pick the right service from the dropdown (usually Wi-Fi on a laptop).

TUN does not turn on

Toggling TUN returns an error mentioning a "service mode".

This is expected for now. TUN routes the entire Mac through Kumo without using system proxy, and that requires a privileged helper that Kumo does not yet install. Until the helper ships, use System Proxy instead. For most use cases the difference is small and System Proxy works today.

Subscription fails to refresh

Open the profile in the Profiles screen, hit Refresh, and watch for an error toast.

A red error with an HTTP code (403, 502, 504): the provider's server is rejecting the request. Check that the URL has not expired and that the credentials in the URL are still valid.
A red error about parsing: the server returned something other than a Clash subscription. Open the URL in a browser to see what it actually returns; some providers return a login page when the subscription has expired.
A red error about timing out and the provider is only reachable through the proxy itself: open the profile detail pane and turn on Refresh through Kumo.

No app icons in Connections

If the Connections destination shows host names but no app icons, make sure the profile is not overriding the find-process-mode setting. Kumo turns that on by default; some user-supplied profiles disable it. The Advanced overrides guide shows how to restore it.

If the Kumo icon is missing from the menu bar:

Bartender, Hidden Bar, or another menu-bar manager might be hiding it. Check its overflow.
Verify Settings → General → Show menu bar icon is on.
If all else fails, restart Kumo.

Auto-update failed

The most common reason is Kumo is not in /Applications. See Stay up to date.

Still stuck?

Open an issue at github.com/ProjectKumo/KumoApp/issues and include:

Kumo version (Settings → About).
macOS version and chip (About This Mac).
A short description of the steps taken.
The last ~50 lines of the Logs screen if Kumo is not working correctly.

Kumo redacts known secrets in logs, but scan the text before pasting it publicly — the subscription URL is the most common leak.