DocsTroubleshooting

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/8 and ::1 stay direct (Akev's own UI runs there). Browsers and terminals launched from Connect do send localhost through Akev. Some clients never proxy localhost (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, and akev start --ephemeral without --data-dir, use a temporary data directory, so every run has a new CA. akev capture -- COMMAND sets the command up with it; for anything else, write it out with --ca-out FILE, or pass --data-dir to 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.
  • akev or akev start while 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 in instance.json. Another one that tries to start there (the desktop app while akev start runs, 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 --ephemeral and akev capture use 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.json from the default data directory, or from --data-dir / AKEV_DATA_DIR when set. The desktop app always uses the default one, so unset AKEV_DATA_DIR, or pass the same --data-dir the instance was started with.
  • An ephemeral instance. akev start --ephemeral and akev capture keep daemon.json in a temporary directory. Start them with --data-dir and pass the same --data-dir to other commands, or address them with --url and --token (AKEV_URL, AKEV_TOKEN); the Web UI link akev start prints contains both.
  • Docker or another machine. For example akev status --url http://localhost:45456 --token "$AKEV_TOKEN". Without --token, --url uses the token from the local daemon.json.
  • Another user account. daemon.json lives 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 akev once.

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 start write logs/akev.log in the data directory (about 5 MB per file; akev.log.1 and akev.log.2 keep the previous ones), readable only by you.
  • Terminal: the CLI prints warnings by default. Add -v for more, -vv for debug output and -vvv for everything (akev -vv). RUST_LOG overrides these, for example RUST_LOG=debug akev. Docker: docker logs akev.
  • Crash reports: if Akev crashes, it writes crashes/crash-<time>.txt in 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/diagnostics in 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, akev command 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 -vv if 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 start banner and akev status print 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.key is your CA's private key, license.json your licence key, daemon.json the access token, wireguard.json your WireGuard keys, and settings.json can 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.

Type to search guides, the CLI and the API.