Help
Troubleshooting
Each entry starts with what you see, then explains why and what to do. If nothing here helps, report a bug.
The proxy isn't on port 8000
Another program (or another Akev) already listens on port 8000. Akev doesn't fail: it takes
the next free port, up to 100 ports higher, and the status bar shows the address it actually
uses. --proxy-port behaves the same way.
Settings → Proxy then says Port 8000 was busy or overridden at startup and offers Use port 8000. Close the other program and press it to move the proxy back without restarting. If the port is still taken, Akev says so and the button turns into Retry.
When the proxy moves, clients set up with the old port need updating: relaunch browsers and terminals started from Akev. If System Proxy is on, its panel offers to point the system at the new address.
The API and web UI of akev use port 45456, or a random free port when that one is busy. The
desktop app always uses a random port.
Nothing shows up in Traffic
Work through these in order:
- Recording is paused. The status bar says Paused and Traffic says Recording is paused.
Traffic is still proxied and rules still apply, but nothing is stored. Click
Resume recording or press
Ctrl/⌘ Shift R. - A filter hides it. The status bar shows two counts (12 / 340 exchanges) and Traffic says No exchanges match. Click Clear filter. The content-type buttons above the list filter too.
- The host is ignored. Hosts in Settings → Capture → Ignored hosts are proxied, but never recorded.
- The client doesn't use the proxy. Compare its proxy setting with the address in the status bar. Browsers and terminals launched from Connect are set up for you. Many command-line tools ignore the system proxy and read environment variables instead: use a Fresh Terminal for those.
- It's a request to
localhost. With System Proxy,localhost,127.0.0.0/8and::1stay direct (Akev's own UI runs there). Browsers and terminals launched from Connect do sendlocalhostthrough Akev. Some clients never proxylocalhost(Go, for example): use the machine's host name or LAN address instead. - It's another device. By default the proxy only accepts connections from this computer. Turn on Settings → Proxy → Allow other devices, and let the port through your firewall.
- It isn't decrypted. Connections Akev doesn't decrypt (hosts on the TLS passthrough list, non-HTTP protocols) appear as tunnel rows only while Settings → Capture → Record tunnels is on. Handshakes the client rejected appear only while Record TLS failures is on. Both are on by default.
- It uses QUIC. See HTTP/3 and QUIC.
Certificate errors
There are two different problems: the client doesn't trust Akev, or Akev doesn't trust the server.
The client doesn't trust Akev
The browser shows a certificate warning or the tool refuses the connection. In Traffic, the attempt shows up as a TLS failure (TLS handshake rejected by the client).
- Browsers and terminals launched from Connect trust the Akev CA without any change to your system. Everything else needs the CA in its trust store: see trust the CA system-wide. Settings → Certificates → Trust on this computer does it in one click (the operating system asks you to confirm), and Trust by hand shows the commands. The status bar says CA not trusted while the system store doesn't trust it.
- Java, Node.js and Python often ignore the system's trust store. Start them from a Fresh Terminal, which points them at the Akev CA, or see certificates.
- Every installation generates its own CA, valid for 10 years. Akev warns when fewer than 60
days are left and never replaces it on its own; an expired CA makes HTTPS interception fail
until you Regenerate it (
akev ca regenerate). After that, clients must trust the new CA: relaunch browsers and terminals started from Akev, and replace the CA wherever you installed it yourself. See expiry. akev capture, andakev start --ephemeralwithout--data-dir, use a temporary data directory, so every run has a new CA.akev capture -- COMMANDsets the command up with it; for anything else, write it out with--ca-out FILE, or pass--data-dirto keep one.- Sites that use HSTS don't let you click past a certificate warning, so trusting the CA is the only fix there.
Apps that pin certificates or bring their own trust store
An app that pins its server's certificate rejects Akev's certificate even when the CA is trusted. The TLS failure in Traffic offers Add host to passthrough (or use Settings → Proxy → TLS passthrough). Connections to those hosts are then tunnelled without decryption, so the app keeps working, but you won't see their contents.
Apps with a trust store of their own need the CA there: Firefox (see below), and Java, Node.js and Python (see above). For Android apps, see Android apps ignore the certificate.
Akev doesn't trust the server
The client gets a 502 page from Akev saying the upstream server's TLS certificate is not
valid (untrusted, expired or for another host). For a server signed by your company's internal
CA, add that CA under Settings → Certificates → Trusted CA certificates. For a test server
with a self-signed certificate, add its host to Ignore certificate errors.
Firefox doesn't trust the certificate
Firefox keeps its own certificate store. When you launch Firefox from Connect, Akev adds
the CA to that Firefox profile with NSS certutil if it is installed (libnss3-tools on
Debian and Ubuntu, Homebrew's nss on macOS). Without it, the first tab asks: tick
Trust this CA to identify websites and click OK, once per profile.
A Firefox launched from Akev keeps the proxy address and CA it started with. After the port changed or the CA was regenerated, launch it again from Connect and Akev restarts it.
For your own Firefox profile, import the CA in Firefox's Settings → Privacy & Security →
Certificates. On Windows and macOS, Firefox can also use the system's store when
security.enterprise_roots.enabled is on (the default on Windows). See
Firefox.
The browser can't open the UI (snap or flatpak)
akev start opens the UI through open-ui.html, a page in the data directory that only you
can read, so the access token never appears on a command line. Some browsers installed as a
snap or flatpak can't open files there.
Use the Web UI link that akev start prints instead; akev status prints it again. The link
contains the access token, so don't paste it anywhere public.
"This session isn't authorized"
The access token changes every time Akev starts (unless you set one with --token or
AKEV_TOKEN). The browser remembers the token for each Akev address, so new tabs, reloads and
bookmarks keep working while that Akev runs; once Akev restarts with a new token, the page says
so and forgets the old one. Open the UI again from the link akev start or akev status
prints, or restart the desktop app. The token is never put back into the page's address.
Lost connection to the Akev daemon means Akev stopped or can't be reached. The tab keeps retrying on its own.
HTTP/3 and QUIC
- Browsers and apps that use Akev as their proxy talk to it over TCP (HTTP/1.1 or HTTP/2
through
CONNECT). They don't send QUIC through a proxy, so their exchanges never show HTTP/3 on the client side. Akev can still use HTTP/3 towards servers: see HTTP/3 to servers. - Accept HTTP/3 from clients is only for clients sent to Akev directly, not for proxied browsers. See HTTP/3 from clients.
- WireGuard mode drops QUIC (UDP port 443), so apps fall back to HTTP/2 or HTTP/1.1 over TCP, which Akev intercepts. See WireGuard mode.
- Transparent capture only redirects TCP. QUIC goes past Akev; browsers fall back to TCP when QUIC fails, and for a program that keeps using QUIC, block UDP port 443. See transparent capture.
The system proxy is still set after Akev quit
If Akev crashed or was killed while System Proxy was on, your system still points at Akev's port, and browsers and apps that follow the system proxy can't connect.
How Akev restores it: before changing anything, it saves your previous proxy settings to
system-proxy-backup.json in the data directory (for runs with another data directory, in
the recovery folder inside the default one), marked with the process that made the change.
Turning System Proxy off, or quitting Akev, puts the old settings back and deletes the
file. When the process that made a change is gone, the next start of Akev (desktop app or
CLI, any data directory) restores the saved settings. Changes made by another Akev that is still
running are left alone.
So the fix is to start Akev once; you can quit it again right away. Without Akev, turn the proxy
off in your system's settings (Windows: Settings → Network & Internet → Proxy; macOS:
System Settings → Network; on Linux, the GNOME or KDE proxy settings). With Akev running,
akev intercept stop system-proxy turns it off too.
Don't delete the data directory while the system still points at Akev: the saved settings are in it.
A phone or other device has no internet
- WireGuard mode: the tunnel routes everything, so while it is on and Akev isn't running (or WireGuard mode is off), the device has no connection. Switch the tunnel off in the WireGuard app.
- Android Device via ADB: Akev sets the device's proxy. Stopping the interceptor or quitting
Akev clears it; after a crash, the next start clears it as soon as the device is connected
again. To clear it by hand:
adb shell settings put global http_proxy :0. - A proxy you entered on the device (iPhone, iPad or Android Wi-Fi settings) stays until you set it back to Off.
Android apps ignore the certificate
On Android, the Akev CA is installed as a user certificate. Browsers trust user certificates (Firefox with its own setting), and so do debuggable apps; release apps targeting Android 7 or later only do when their network security configuration allows it.
On a rooted device or an emulator (adb root, or su), the Android interceptor also trusts
the CA as a system CA until the device restarts, so release apps trust it too: see
system trust. Restart apps that were
already running. Apps that pin their certificates still refuse it.
For your own app, let debug builds trust user certificates, for example with
<debug-overrides><trust-anchors><certificates src="user"/></trust-anchors></debug-overrides>
in network_security_config.xml. For other apps, add their hosts to TLS passthrough so they
keep working, undecrypted.
A second Akev, and daemon.json
- The desktop app runs once: opening it again brings its window to the front.
akevorakev startwhile Akev already runs with the same data directory doesn't start a second one: it prints Akev is already running and opens that instance's UI. This includes the desktop app, which uses the default data directory.- One Akev per data directory. A running Akev holds a lock (
akev.lock) on its data directory and records itself ininstance.json. Another one that tries to start there (the desktop app whileakev startruns, for example) stops with an error naming the running one: its process id, whether it is the desktop app or the command line, and its version. Quit that one first, or use another--data-dir. akev start --ephemeralandakev captureuse their own temporary directory, so they always start a new instance. While another one holds the port, its proxy takes the next free one.
The running instance writes daemon.json to the data directory: its process id, API address,
access token, proxy port and version, readable only by you. CLI commands use it to find and
authenticate to Akev, and a clean exit removes it. One left behind by a crash is ignored once
nothing answers at its address, and the next start replaces it. You can delete it whenever
Akev isn't running.
The CLI can't find the running app
akev status says Akev is not running although it is:
- Another data directory. The CLI reads
daemon.jsonfrom the default data directory, or from--data-dir/AKEV_DATA_DIRwhen set. The desktop app always uses the default one, so unsetAKEV_DATA_DIR, or pass the same--data-dirthe instance was started with. - An ephemeral instance.
akev start --ephemeralandakev capturekeepdaemon.jsonin a temporary directory. Start them with--data-dirand pass the same--data-dirto other commands, or address them with--urland--token(AKEV_URL,AKEV_TOKEN); the Web UI linkakev startprints contains both. - Docker or another machine. For example
akev status --url http://localhost:45456 --token "$AKEV_TOKEN". Without--token,--urluses the token from the localdaemon.json. - Another user account.
daemon.jsonlives in each user's own data directory.
The Akev daemon … rejected the API token means a token you passed, or one left in
AKEV_TOKEN (for example for a Docker instance), overrides the one in daemon.json. Unset it.
The desktop app on Linux
The desktop app is built on WebKitGTK 4.1 and GTK 3. The .deb and .rpm packages declare
both as dependencies, so install them with apt or dnf as shown on the
download page to get them too.
If the app doesn't start, run it from a terminal (for the AppImage,
./Akev_<version>_amd64.AppImage) and read the error it prints (Akev failed to start: …).
Meanwhile the akev command line runs the same core and serves the same UI in your browser.
First launch on macOS and Windows
Akev's release packages aren't code-signed yet, so the operating system asks you to confirm the first launch:
- macOS: open System Settings → Privacy & Security and choose Open Anyway.
- Windows: when SmartScreen says Windows protected your PC, choose More info → Run anyway.
- The CLI archive on macOS, downloaded with a browser, needs
xattr -d com.apple.quarantine akevonce.
To check a download, compare its checksum with SHA256SUMS: see the
download page.
Pro features answer 402 pro-required
Starting or using a Pro feature without Pro fails with a message such as WireGuard mode needs
Akev Pro. Start the free 14-day trial or enter a license key in Settings → License. Over the
API that is a 402 with the code pro-required and the feature id; MCP tools return an error
naming the feature.
Check Settings → License or akev license status. Pro is off when there is no key and no
running trial, when the trial has ended, when the key's year of updates ended before this
release (updates-ended), or when the key isn't accepted (copy it again, completely, from the
email). Nothing is deleted meanwhile: Pro settings and rules stay stored and work again once Pro
is back. See licensing.
The trial was already used. Starting it again answers 409 trial-unavailable: The trial
was already used on this computer, or a license already covers this version. The trial runs
once per user account on a computer, and every data directory shares it.
Ephemeral sessions (--ephemeral, akev capture) can't start the trial, but they use one
that is already running. In CI, pass a key with AKEV_LICENSE instead.
For questions about keys, receipts or renewals, write to support@akev.dev.
Settings or rules were reset
If settings.json or rules.json can't be read, Akev moves it aside as settings.json.bak or
rules.json.bak, starts with defaults and logs a warning. Your previous file is still there.
Logs, crash reports and diagnostics
Everything here stays on your computer until you choose to share it.
- Log file: the desktop app and
akev startwritelogs/akev.login the data directory (about 5 MB per file;akev.log.1andakev.log.2keep the previous ones), readable only by you. - Terminal: the CLI prints warnings by default. Add
-vfor more,-vvfor debug output and-vvvfor everything (akev -vv).RUST_LOGoverrides these, for exampleRUST_LOG=debug akev. Docker:docker logs akev. - Crash reports: if Akev crashes, it writes
crashes/crash-<time>.txtin the data directory: version, OS, the error, a backtrace and the last log lines, with the API token, credentials and cookies scrubbed out and never any captured traffic. The newest 30 are kept. If the desktop app can't start its engine, it shows the reason in a dialog. - Diagnostics: Settings → About → Copy diagnostics copies the version, operating
system, uptime, counters, a summary of your settings (without secrets), recent warnings and
the names of crash reports: no tokens and no captured traffic. The same is
GET /api/diagnosticsin the API.
The logs folder also holds the output of programs Akev launched (browsers, Fresh Terminal,
Electron apps), which helps when a launched browser doesn't start. Settings → About shows
the version, platform, data directory and API address, and akev status --json prints the
running instance's full status.
Reporting a bug
Settings → About → Report a problem opens a new GitHub issue filled in with the diagnostics above; you review and edit everything before you submit it (in the desktop app, also Help → Report an Issue…). Or open one yourself at github.com/akevdev/akev/issues and paste Copy diagnostics. Include:
- the Akev version (
akev --version, or Settings → About), - how you run Akev (desktop app,
akevcommand line or Docker) and how you installed it, - your operating system and its version,
- what you did, what you expected and what happened instead,
- the relevant part of
logs/akev.log, or a crash report, or a log with-vvif the problem is reproducible (read it first: logs can contain URLs and host names).
Captures can contain secrets. HAR exports, .akev sessions and screenshots of Traffic hold
everything that was recorded: cookies, Authorization headers, API keys and request and
response bodies. Export with Redact secrets on (see sessions),
reproduce against a test server, or remove them before you attach anything.
Also check what you paste:
- The
akev startbanner andakev statusprint the Web UI link, which contains the access token. With an active licence, the banner also shows your name. - Never attach files from the data directory:
ca.keyis your CA's private key,license.jsonyour licence key,daemon.jsonthe access token,wireguard.jsonyour WireGuard keys, andsettings.jsoncan hold client-certificate passphrases. To share your setup, use Settings → Data → Export configuration: it leaves out client-certificate passphrases, and your licence key isn't part of it.
Security problems go privately to security@akev.dev, not to a public issue.