All docs sections
First, open the Overview screen. At the top, it shows the most serious problem and a button that fixes it. If the cause isn’t clear, find your case in the table below.
Is Routekeeper to blame? Turn off the Routekeeper On switch in the menu of the menu bar icon. Rules stop applying, and all connections go direct, past the proxy. If everything works now, the problem is in your rules or the proxy. If not, it’s most likely the network or another program. Don’t forget to turn the switch back on.
Quick check
| What you see | Why it happens | What to do |
|---|---|---|
| Nothing opens in any app | Block All mode is on. Or Routekeeper couldn’t read its settings and is blocking everything. Or an old Routekeeper extension or another VPN program is running alongside it. | Check the mode in the icon’s menu and the banners at the top of the window. About the lock, see below; about banners, the list of messages; about VPNs, Limitations. |
| One app has no network at all | Its proxy is unreachable, and Routekeeper doesn’t let such connections go direct. Less often, it’s a Block rule or a prompt that’s waiting for an answer in Ask mode. | On Overview, click Check All. If the proxy is unreachable, move the routes. If the icon’s menu has Waiting for answer, answer the prompt. |
| An app goes direct instead of through the proxy | There’s no route, child processes are turned off, another rule took over the address, or the connection has no site name. | Go through the list in An app goes around the proxy. |
An app on a proxy can’t open an address on your home or work network: an internal git server, a portal, a printer. The error can be cryptic, for example tlsv1 alert protocol version from git | The connection went to a remote proxy, which can’t reach your network. Routekeeper normally lets such addresses go direct by itself, but not when Settings → Network → Local networks go direct is off, when the address is named in a Through Proxy rule, or when the company’s internal servers sit on public addresses. Version 0.3.0 doesn’t have this setting yet. | In Monitor, select the connection and look at the Decision field. Create a rule: the company’s subnet or domain → Direct, for example 10.0.0.0/8 or *.corp.example. How to write the address is in Rule fields. |
| The proxy check fails | Wrong server, port, type, login or password. An IP instead of a domain name for HTTPS. The local client isn’t running. | Find the error text in the list of messages. |
| Everything works, but slowly | The server is far away or overloaded. A response time of 1500 ms or more is marked “slow”. The first connection of a program that has just started can be delayed by a fraction of a second. A single connection sometimes waits 1.5–4 seconds: its connection to the proxy stalled, and Routekeeper opened a new one. | A distant server that works fine shows 500–800 ms. That’s normal. If you have a closer proxy, move the routes to it. |
| The browser goes around the proxy | The browser opens some sites over QUIC, sends its own DNS queries, or goes through the proxy only for a service. Old connections stayed on the previous route. | Check Block UDP and QUIC on the proxy. Recipes: one service in the browser and DNS over HTTPS. Restart the browser. |
| No icon in the menu bar | Routekeeper isn’t running: for example, after a restart if Open at login is off. Or the icon is hidden behind the MacBook’s notch or under other icons. | Open Routekeeper from the Applications folder or with Spotlight: the icon appears. If you still can’t see the icon, open Routekeeper once more. Then its window opens. Rules work even when the app isn’t running: the network extension applies them. |
| The window doesn’t open, and there’s no icon in the Dock | Routekeeper is a menu bar app. It appears in the Dock only while its window is open. | Click the menu bar icon → Open Routekeeper (⌘O). Or right-click the icon, or click it while holding ⌥. Or open Routekeeper again from Finder or Spotlight. |
| The monitor is empty | Routekeeper is turned off with the switch, and then the monitor doesn’t record. Or the macOS permissions aren’t given. | Turn on Routekeeper On. If the window shows the welcome screen, go through its steps (permissions). |
macOS permissions
Routekeeper works through a network extension, and macOS asks for permission three times: to turn on the extension, to filter network content and to add a proxy configuration. Until all three are given, the Routekeeper window shows the welcome screen with steps instead of the sections. Installation is described step by step in the Quick start. Here is what to do if something went wrong.
You clicked “Don’t Allow”
- In the window about filtering network content. Open the Routekeeper window. On the welcome screen, at step 2, click Turn On Filter again. macOS asks again. Click “Allow”.
- In the window about the proxy configuration. The same way: step 3 → Turn On Proxy → “Allow”.
Where to allow the extension
You do this step in System Settings, and the path depends on your macOS version.
- macOS 15 and later. System Settings → General → Login Items & Extensions → Network Extensions. Turn on Routekeeper. If the general list of extensions opens, switch it to By Category and open Network Extensions. The Open System Settings button on the welcome screen and Open Settings in the hint window take you straight there.
- macOS 14. System Settings → Privacy & Security. Scroll down to the message that system software from developer Ilya Bazhenov was blocked from loading. Click “Allow” and enter the administrator password. Routekeeper’s hints describe only the macOS 15 path, so on macOS 14 open System Settings yourself. If there’s no message, click Try Again or Install at step 1: macOS shows it again.
In the list, the extension is called “Routekeeper Extension”, and in versions 0.2.x “Routekeeper Network Extension”. Only a user with administrator rights can allow the extension.
The extension was turned off in System Settings
If you turn Routekeeper off in the list of network extensions, the filter and proxy stop working, and the Routekeeper window shows the welcome screen again. At step 1, click Install or Try Again and turn the extension back on in the same list. If Routekeeper’s configurations were turned off or removed in System Settings → Network, open the Routekeeper window. If it shows the welcome screen, repeat steps 2 and 3. If not, and the status line says “Proxy provider isn’t running”, click Settings → Extension → Reinstall.
macOS asks for a restart
Sometimes, after the extension is installed, step 1 shows “Restart your Mac to finish installing.” Restart your Mac and open Routekeeper. After a restart, the extension, filter and proxy start by themselves. The Routekeeper window opens by itself only if Open at login is on (Settings → General).
A Mac managed by an organization
On a work Mac, an administrator can forbid system extensions or network filters with a management profile (MDM). Then the switch in System Settings is missing or can’t be turned on, and you can’t change this yourself. Contact your administrator.
Details: what to tell the administrator
Routekeeper installs a system network extension with two configurations: a network content filter (sockets) and a transparent proxy (app proxy). The developer’s Team ID is N577X226Q5. The extension’s identifier is app.getroutekeeper.mac.extension; in versions 0.2.x, it’s dev.ilyabazenov.appproxy.extension. The app must be in /Applications.
Other VPN programs and network filters can also get in the way: see Other VPNs and network extensions.
An app goes around the proxy
The quickest way to find the cause is the monitor. Open Monitor, type the app’s name in the search field and select its connection. The Decision field at the bottom says why the connection went this way: “rule: …” with the app and the address, “no rule — Proxy Only mode”, “Routekeeper is off” and so on.
- Does the app have a route? Where all of an app’s traffic goes is set in the Apps section, not in Rules. The app’s row should have a route like Proxy: …, and the switch on the right should be on. If the Decision field says “no rule”, there’s no route. How to add one: An app’s route.
- Is it the right app? Routekeeper recognizes an app by its signature. A beta version, a copy from another store or a second browser are different apps. Add the one you need.
- Is Include Child Processes on? Right-click the app’s row. If the item is off, the app’s helper processes and the programs it launches follow their own rules. In the Leaks section, such connections are marked Process outside the rule. For details, see Child processes.
- Did another rule take over the address? A rule for a specific address, or a service, wins over the app’s route. For example, the “Russian sites” service with the Direct route, or the rule
*.example.com→ Direct, sends these addresses direct even for an app on a proxy. The Decision field shows this rule. The order is described in Which rule wins. - Does the connection have a site name? Domain and service rules apply only when the app passed a name. Connections to a bare IP and most QUIC connections carry no name and follow the app’s route. If you’re counting on a service rule and the browser’s route is Direct, you need the recipe for one service in the browser. For details, see Rules by site name.
- Is it an old connection? Open connections don’t move to a new route. Restart the app.
- Is going direct allowed when the proxy fails? If Settings → Network → If the proxy is down, go direct is on, connections go direct while the proxy is unreachable.
Details: what always goes direct
- Connections to the same Mac (
127.0.0.1,::1), that is, loopback. There are built-in rules for this, and also the Leave localhost alone switch in Settings → Network. - Addresses on a local network (your home network, a corporate VPN, Tailscale) from an app that goes through the proxy as a whole. This is the Local networks go direct switch in Settings → Network. The Decision field says “local network, past the proxy of the rule for …”.
- Connections from any app to the address and port of a proxy added to Routekeeper. The Decision field says “connection to the proxy server”.
- Routekeeper’s own connections: proxy checks, updates, service lists.
- UDP DNS queries to port 53 from an app on a proxy: they’re let through directly and flagged as DNS around the proxy. For a browser, there’s a recipe.
- UDP from an app on a proxy if that proxy has Block UDP and QUIC off. Such connections are flagged as UDP around the proxy.
- New connections in the first seconds after the extension restarts or updates: see Limitations.
What Routekeeper flags as a connection around the proxy and what it doesn’t is described in What Routekeeper notices and what it doesn’t.
App messages
Proxy errors
You see them in three places: next to the Check button in the Proxy section, in Monitor (the Route column shows Error, and the reason is in the connection’s details) and in the notification “…: proxy failed”.
| Message | What it means | What to do |
|---|---|---|
| The proxy didn’t answer in time | The server didn’t answer within the allowed time: the check waits 10 seconds, an app’s connection 15. If the connection to the proxy stalls, Routekeeper opens new attempts alongside the first one after 1.5 and 4 seconds, so the error means none of them worked. The server is off, the address or port is wrong, or the server doesn’t answer from your network. | Check the server and port. Try from another network, for example through your phone’s hotspot. If it’s your own server, see server troubleshooting. |
| Couldn’t connect to the proxy: … (followed by the reason from macOS, for example “Connection refused”) | Nothing accepts connections at this address and port. | Check the port. For a local client, check that it’s running and which port it listens on. |
| Couldn’t connect to the proxy: TLS: the proxy’s certificate failed validation | HTTPS proxy: the server’s certificate doesn’t match the name in the Server field, has expired, or was issued by an authority that isn’t trusted. | In the Server field, enter the domain name the certificate was issued for, not the IP. |
| Couldn’t connect to the proxy: TLS: TLS error (code) | Another failure of the encrypted connection. Often the HTTPS type is chosen for an ordinary HTTP proxy. | Check Type: choose HTTPS only if the proxy itself works over TLS. |
| SOCKS5: wrong login or password | The proxy rejected the login and password. | Enter them again and click Save. |
| SOCKS5: the proxy requires a login and password | The proxy doesn’t let anyone in without signing in, and no login is set. | Fill in Login and Password. |
| SOCKS5: the proxy accepted no authentication method | The proxy expects a different way of signing in than the one Routekeeper offers. | Check whether a login is needed. Routekeeper supports SOCKS5 without signing in and with a login and password. |
| SOCKS5: … (for example, “host unreachable”, “connection refused”, “connection not allowed by the proxy’s rules”) | The proxy works, but it couldn’t or wouldn’t connect to the site. | The cause is on the proxy’s or the site’s side. Try another site. If every site gives the error, check the proxy server’s settings. |
| HTTP: the proxy requires authentication (407) | The HTTP proxy didn’t accept the login and password, or they’re missing. | Check the login and password. Routekeeper supports only signing in with a login and password (Basic), without NTLM or Kerberos. |
| The HTTP proxy answered … (a code and text, for example 403) | The proxy refused to connect to this address or port. | Work proxies are often restricted like this. Ask your administrator which addresses and ports are allowed. |
| The proxy closed the connection | The proxy dropped the connection without explaining anything. | Often the Type is wrong: SOCKS5 instead of HTTP or the other way around. It also happens when the server is overloaded or has limits. |
| Proxy protocol error: … | The answer doesn’t look like a proxy of the chosen type. | Check Type and Port: maybe this port has another type of proxy, or isn’t a proxy at all. |
| Server … not found: DNS has no such name | The proxy server’s name doesn’t exist. | Check Server in the proxy card: a typo, an expired domain. |
| Couldn’t find the address of server …: this network’s DNS doesn’t resolve it, and DNS over HTTPS is unreachable | The network won’t give out the proxy server’s address, and getting around its DNS didn’t work. | Enter the Server IP address in the proxy card, see How Routekeeper finds the server’s address. |
| proxy not found (in the monitor) | A rule points to a proxy that no longer exists. The connection is blocked, not sent direct. | Open the rule and choose another Action. |
| proxy provider isn’t running (in the monitor) | The part of Routekeeper that passes traffic to the proxy hasn’t started yet: for example, right after the Mac starts up or the extension restarts. The connection is dropped so that it doesn’t go direct. | Usually the app tries again by itself in a few seconds. If the error doesn’t go away, see the “Proxy provider isn’t running” status below. |
| No connection to the network extension | The window can’t reach the extension. | See the “The network extension isn’t responding” banner below. |
Banners at the top of the window
| Banner | What it means | What to do |
|---|---|---|
| Connecting to the network extension… | The window is connecting to the extension. This is normal in the first seconds after launch or an update. | Wait. |
| The network extension isn’t responding, with the Details and Reinstall Extension buttons | The extension is on, but it hasn’t answered the window for 10 seconds. This most often happens after an update. Rules keep working, but you can’t change them, and the proxy may not be running. | Click Reinstall Extension (the icon’s menu has the same item). If that doesn’t help, restart your Mac. For details, see below. |
| Settings couldn’t be read, all connections are blocked | The extension couldn’t read the settings file and is blocking everything. | See All connections are blocked. |
| An extension from an old version of Routekeeper is running | After the move from 0.2.x, the old extension stayed on and also handles traffic. | Turn off “Routekeeper Network Extension” in System Settings. Leave “Routekeeper Extension” alone. For details, see Moving from 0.2.x. |
| A network extension update is available (current: …), with the Update… button | The app was updated, but the extension is still the old one. Starting with version 0.5.0, the banner stays only if the extension couldn’t update by itself. | Update it when it’s convenient: see Updates. |
| An orange bar with the error text and a close button (×) | The last error, for example when saving a rule. | Read the text. The bar closes with the × button, or by itself after 12 seconds. |
The “Settings couldn’t be read, all connections are blocked” and “An extension from an old version of Routekeeper is running” banners appeared in the version after 0.2.1.
Status line
A short status is shown in the icon’s menu under the word Routekeeper, and in the panel at the bottom of the sidebar.
| Status | What it means and what to do |
|---|---|
| Waiting for approval in System Settings | macOS is waiting for you to allow the extension: see permissions. |
| Setup isn’t finished | A permission is missing. Open the window and go through the steps of the welcome screen. |
| Connecting to the extension… / Extension not responding | The same as the banners above. |
| Off | The Routekeeper On switch is off: rules don’t apply, and everything goes direct. |
| All connections are blocked | The settings couldn’t be read: see below. |
| Proxy provider isn’t running | Routekeeper’s proxy configuration isn’t working: it was turned off in System Settings → Network, or it didn’t start. Open the window. If it shows the welcome screen, click Turn On Proxy. If not, click Settings → Extension → Reinstall. |
| Proxy “…” is unreachable | The main proxy failed its check: see The proxy stopped answering. |
| No apps through a proxy | No app or service is sent through a proxy. Add them in Apps. |
Other messages
| Message | What to do |
|---|---|
| macOS installs system extensions only for apps in the Applications folder. | Click Move to Applications and Relaunch. If a copy of Routekeeper is already in Applications, it goes to the Trash. |
| Couldn’t install: … | The reason comes from macOS. Check that Routekeeper is in Applications and that you have administrator rights, and click Install again. If that doesn’t help, restart your Mac. |
| Restart your Mac to finish installing. | Restart your Mac. |
| The clipboard has no proxy string. Expected something like socks5://user:pass@host:1080 | Copy the whole line, including the port. Which formats Routekeeper understands is described in Paste a proxy line. |
| Enter a server and a port (1–65535) | Fill in Server and Port. |
| Can’t parse the destination “…” | The address in the rule is written in a way that Routekeeper doesn’t understand: see Rule fields. |
| Routekeeper couldn’t read its settings, so they can’t be changed. Update Routekeeper or reset the settings. | See below. |
| Diagnostics not collected: … | Try again. Check that there’s free space on the disk. |
Reinstalling and stopping the extension
The extension’s status is shown in Settings → Extension, in the Status section. If everything is fine, it says: Network extension “Active”, Filter “On”, Proxy “Running”. The Extension version is shown there too.
Reinstall
This helps when the extension has stopped responding, for example after an update.
- Open Settings → Extension and click Reinstall. The Reinstall Extension button on the banner and in the icon’s menu does the same.
- Routekeeper removes the extension and installs it again right away. For a few seconds, the filter and proxy are off: open connections through the proxy break, and new ones go direct during this time. Then the filter and proxy turn on by themselves.
- If macOS asks you to allow the extension again, allow it as you did during installation (permissions).
Rules, proxies and passwords are kept when you reinstall. If the “The network extension isn’t responding” banner doesn’t go away, restart your Mac.
Stop…
Settings → Extension → Stop… → Stop. Routekeeper’s filter and proxy are turned off at the system level. Apps start going online directly, past the proxy, and firewall rules stop applying. The extension stays installed, and the rules stay on disk. After that, the Routekeeper window shows the welcome screen.
The Routekeeper On switch doesn’t undo “Stop…”. It only turns the rules on and off inside a running filter and proxy. To bring the filter and proxy back after you stopped them, open Settings (icon’s menu → Settings…) → Extension and click Reinstall: after reinstalling, Routekeeper turns them on by itself. If the window shows the welcome screen with the Turn On Filter or Turn On Proxy buttons, you can click those too.
How the switch, “Stop…” and “Delete…” differ is summed up in a table in How to turn it off.
All connections are blocked
The banner “Settings couldn’t be read, all connections are blocked” means that the network extension couldn’t read the file with your rules and proxies. To make sure nothing goes around the proxy, Routekeeper then blocks everything. Only connections within this Mac, Routekeeper itself and the system DNS service are let through. This behavior appeared in the version after 0.2.1.
Why it happens
- An older version of Routekeeper was installed over newer settings. The newer version may have saved the settings in a form the older one doesn’t know. Then the banner says: “They were saved by a newer version of Routekeeper”.
- The settings file is damaged. Then the banner says: “The settings file is damaged”.
What to do
- Click Check for Updates on the banner. Routekeeper itself is still allowed to go online in this state. Install the new version: it will read the settings, and everything will work as before.
- If there’s no update or it didn’t help, click Reset Settings… → Reset. Your rules and proxies are deleted, and apps go direct until you set them up again.
- The reset doesn’t delete the old file: it stays next to the new one, named
config.broken-number.json, in the/Library/Application Support/Routekeeperfolder.
While the settings can’t be read, you can’t change them: Routekeeper answers “Routekeeper couldn’t read its settings, so they can’t be changed…”. You can turn Routekeeper off with the switch, but only until the extension restarts. After that, everything is blocked again.
Don’t install an old version over a new one. If you need to go back, save your rules first: Rules → Import and Export → Export… (proxy passwords aren’t saved to the file). For details, see Import and export.
Details: the backup and version 0.2.1
Only an administrator can open this folder. To see what’s in it:
sudo ls -l "/Library/Application Support/Routekeeper"The config.broken-…json file is JSON with your rules, proxies and settings. It has the proxy passwords in plain text, so don’t attach it to a public bug report. The number in the name is the time of the reset in seconds since 1970.
Version 0.2.1 has no lock. It renames an unreadable file to config.broken-…json in the /Library/Application Support/AppProxy folder, and Routekeeper starts with clean settings: all apps go direct.
Collect diagnostics
A diagnostics archive helps work out what the problem is. Routekeeper doesn’t send it anywhere: the archive simply appears on your Desktop.
- Open the Routekeeper window. In the menu bar at the top of the screen, choose Help → Collect Diagnostics…. Or open Settings → Extension and click Collect… in the If Something’s Wrong section.
- After a few seconds, Finder shows the file
Routekeeper-diagnostics-date time.zipon the Desktop. - Unzip it and look through it before you send it to anyone.
What’s in the archive
| File | What’s inside |
|---|---|
info.txt | The Routekeeper and macOS versions, the status of the extension, filter and proxy, the mode, the number of rules. For each proxy: its name, type, server address and port, and the result of the last check. |
config.json | Rules, proxies and settings. There are no passwords, but there are server addresses and logins. |
connections.json | The last 500 connections: app, address, port, route, error. |
log.txt | Routekeeper’s internal log for the last 30 minutes, including the addresses that apps connected to. |
The archive contains personal data: the addresses of sites you opened, and proxy addresses and logins. Bug reports on GitHub are public. Before you attach the archive, remove from it anything you don’t want to show.
Details: the log without an archive
If the Routekeeper window doesn’t open, you can save the log with a command in Terminal. The file appears on your Desktop.
log show --last 30m --info --predicate 'subsystem == "app.getroutekeeper.mac"' > ~/Desktop/routekeeper.logFor versions 0.2.x, the subsystem has a different name:
log show --last 30m --info --predicate 'subsystem == "dev.ilyabazenov.appproxy"' > ~/Desktop/routekeeper.logReport a problem
Bugs and suggestions go to the project’s GitHub Issues. You need a GitHub account.
- Check whether your case is on this page or in Limitations.
- If the problem happens again, collect diagnostics right after it shows up, and look through the archive.
- In the Routekeeper window, choose Help → Report a Problem…. A form for a new issue opens in the project’s GitHub Issues.
- Write down:
- the Routekeeper version: it’s in Settings → General → Version, for example “0.2.1 (10)”;
- the macOS version and the Mac model: Apple menu → “About This Mac”;
- the mode and the proxy type (SOCKS5, HTTP or HTTPS), without the address or password;
- what you did, step by step, what you expected and what happened.
- Drag the diagnostics archive into the message field.
Everyone can see reports on GitHub. Don’t paste passwords, keys or addresses you don’t want to show. If you can’t share the archive, describe the problem without it and say that you have the archive.
Checked against the Routekeeper code (version 0.2.1 and the one after it) on October 4, 2026.