Skip to content

Troubleshooting

Always start with the status of the background service:

sh launch/tegvia-service.sh status

(launch\tegvia-service.cmd status on Windows). It shows whether the service is active, whether settings.json points at the proxy, the console URL, the log paths and, when nothing listens on the port, the end of proxy.stderr.log. See Background service. If you use the standalone launcher, read the messages printed in its terminal instead.

"Restart Tegvia" below means: restart for the service (see Background service), or stop the standalone launcher with Ctrl-C and start it again.

Useful files

In the Tegvia data folder (~/.tegvia, or the folder set by TEGVIA_HOME). tegvia-service status prints the paths of the two proxy logs, which sit in that folder:

File Content
state/install.log What install / uninstall printed, run after run (no secrets).
state/tray.log Tray icon log, including crashes.
state/bootstrap.log Dependency install (pip errors).
proxy.stderr.log Application log of the proxy started by the service or in the background (errors, tool calls) and why it failed to start.
proxy.stdout.log Other plain output of that proxy (start-up banner).
tegvia.db Session log database (see Usage).
tegvia.db-wal, tegvia.db-shm Normal side files of the database while the proxy runs.
tegvia.db.bak-v<n> Copy made before a database upgrade; can be deleted once all works.
tegvia.db.pending Log entries waiting to be saved while the database is unavailable; deleted automatically once saved.

The two proxy.*.log files are only written for a proxy started by the service or by the launcher's background mode (not one you start by hand, or the launcher in the foreground, whose output stays in the terminal). They are readable by you only (Linux, WSL, macOS) and are kept small: each one is capped at 10 MiB. When full, it becomes .1 (for example proxy.stderr.log.1), the previous .1 becomes .2, then .3, and the oldest is deleted: at most 4 files per log, no line is lost or cut in two. The credential headers (x-api-key, Authorization) are truncated in them as everywhere else.

The proxy does not start

Run tegvia-service status. If the proxy is not listening, it prints the paths of both logs (in the data folder) and shows the end of proxy.stderr.log, which holds errors raised after startup and the refusals for a busy port or an invalid settings.json. Failures that happen earlier (broken config.py, refused data folder, Python too old) are not written to that file. To diagnose them, run the standalone launcher in a terminal: the message is printed there. Under the service, on Linux/WSL they are in the user journal (journalctl --user -u tegvia.service); on macOS and Windows no copy is kept, so run the launcher in a terminal. Typical messages:

  • tegvia: error in .../config.py, line N: ...: your config.py has a mistake on that line. Fix it, or remove or rename the file.
  • tegvia: refusing to run .../config.py: not owned by the current user or writable by group or others: fix the permissions (chmod 600, and the file must be yours) or remove the file. It is not run until then.
  • The data folder is refused (not owned by you, or writable by group or others, on Linux, WSL, macOS): run chmod go-w ~/.tegvia (or on the TEGVIA_HOME folder) or fix its ownership. The proxy exits before reading config.py and nothing is written into that folder until then.
  • A message saying the port is already in use: see Port 8736 is already in use.
  • Python X.Y.Z found, but Python 3.11 or newer is required: the proxy was started by a Python that is too old. Install Python 3.11 or newer (Installation), then restart Tegvia.
  • A missing dependency or an import error: see "dependency install failed".

Once fixed, restart Tegvia. If the log shows no such line, the proxy may not have written anything yet. If the proxy output log files cannot be written, for example because a symbolic link sits at their name, they are not followed and the proxy falls back or the write fails.

A configuration error (port busy, unreadable settings.json, broken config.py) is not retried by the service on Linux, WSL and macOS: fix the cause, then run start. On Windows, Task Scheduler retries up to 3 times (see Background service).

Claude Code shows API Error 500, 502 or 504 with a Tegvia: message

When something goes wrong between Claude Code and the API, Tegvia answers with an error whose text starts with Tegvia: instead of a bare failure. Example:

API Error: 502 {"type":"error","error":{"type":"api_error","message":"Tegvia: could not reach the Anthropic API (ClientConnectorError) (request 3fa9c1d2)."}}

The message holds a request id (8 hexadecimal characters) that identifies the exchange. What each case means:

  • 500, "internal error before sending the request upstream": Tegvia failed before sending. Nothing was sent to Anthropic.
  • 500, "error while handling the Anthropic response": Tegvia failed while handling the response. The response was not passed on.
  • 502, "could not reach the Anthropic API": the API could not be reached (network, DNS, TLS) or the connection was cut.
  • 504, "the Anthropic API timed out": the API did not answer in time (see the timeouts below).

When the response is already streaming, the status stays the API's and the same error arrives as a final error event, after the text already shown. Claude Code retries 5xx errors by itself, so a one-off error often goes away on its own.

Where to read the detail:

  • proxy.stderr.log in the data folder: a warning with the request id, the stage and the exception type (see Getting more detail for the full trace);
  • the web console: the outcome of the exchange (error_before_sending, upstream_error, error_response), and the Outbound flows page.

For a 504, or an answer cut off during a long silence, raise UPSTREAM_READ_TIMEOUT_SECONDS in your config.py (default 600 s, the maximum silence between two pieces of data; there is no total limit) and, if the connection itself is slow to open, UPSTREAM_CONNECT_TIMEOUT_SECONDS (default 30 s). Then restart Tegvia.

Note

An exchange recorded as client_closed is not a failure: Claude Code closed the connection before the end of the response, for example when you pressed Escape.

Error ending with SSEEventTooLarge

If the message reads "error while handling the Anthropic response (SSEEventTooLarge)", Tegvia received a single streamed event larger than 16 MiB. This only happens with a target other than the Anthropic API (a gateway set through TEGVIA_TARGET or its console override) that sends such an event. The limit is fixed and cannot be changed. Look at proxy.stderr.log and at the error_response outcome in the console, then check the gateway's streaming behaviour.

Error ending with SSEFramingError

If the message reads "error while handling the Anthropic response (SSEFramingError)", Tegvia received a streamed response in which a line other than the very first of the stream starts with a UTF-8 byte order mark (BOM, bytes EF BB BF). Claude Code strips this mark at the start of every line, while the SSE standard strips it only at the start of the stream: such a stream could slip a tool call past Tegvia's checks, so Tegvia refuses it and stops the response. This only happens with a target other than the Anthropic API (a gateway set through TEGVIA_TARGET or its console override) or an intermediary that alters the stream. Look at proxy.stderr.log and at the error_response outcome in the console, then fix the gateway so it does not insert a BOM in the middle of the stream.

Warning "stream ended inside an SSE event, N bytes dropped"

This warning in proxy.stderr.log means the upstream stream stopped in the middle of an event (truncated or malformed upstream response). The incomplete part (N bytes) is not delivered to Claude Code. The exchange outcome stays relayed. It is not written when Tegvia itself cut the stream, when the stream failed or when Claude Code closed the connection.

Responses do not start with "Protected by Tegvia"

The session is not going through the proxy.

The watermark is expected only on the first text of each answer (after each question you ask), not on every text between tool calls: a missing watermark on a text after a tool call is normal. It can also be missing when the turn starts with a sub-agent or a helper request: the watermark may have gone to that text instead of the visible answer.

  1. Did you just install or start Tegvia? Restart Claude Code: a session already open keeps the address it read at its start.
  2. tegvia-service status says the service is not active, or that settings.json is not redirected → run start (service) or start the standalone launcher, then restart Claude Code. Check that no ANTHROPIC_BASE_URL set elsewhere (shell environment variable, project settings .claude/settings.json) takes precedence.
  3. Protection was paused from the console: see the section Settings and protection.

"no usable system Python 3.11+ found on PATH"

The full message is:

Tegvia: no usable system Python 3.11+ found on PATH (virtual-environment copies are skipped). Install one, make sure it's on PATH, then try again.

No usable Python 3.11+ was found, and not even a 3.10 (otherwise see the next section). Install one by following Installation, check it is on the PATH, then run the command again. Python copies inside a .venv are deliberately ignored.

Windows — Smart App Control: python.exe copies inside a virtual environment can be blocked by Windows security policy. Tegvia avoids them on purpose: install a "system" Python from python.org.

Python too old: Tegvia does not start

Tegvia found a Python 3.10 but none 3.11 or newer. It cannot run. The installer, the service commands or the launcher stop with exit code 1 and print a message like this (the version and path are those of your Python):

Tegvia needs Python 3.11 or newer, but only Python 3.10.12 was found (/usr/bin/python3).
See install.html#python in the Tegvia docs to install a newer Python.
After installing Python 3.11+, run Tegvia again.

Nothing is changed on your machine by this message. Claude Code itself keeps working, but without Tegvia if it was not running.

What to do: install Python 3.11 or newer (Installation), then run the command again (install, start or restart for the service, or the launcher).

"dependency install failed"

The dependency install failed. Read state/bootstrap.log in the data folder. Common causes: no access to PyPI (corporate proxy: configure pip), disk space, Python too old. Fix it, then restart Tegvia.

If the message instead starts with Tegvia: pip is not available for followed by the path of a Python, that Python has no pip (typical of a python3.11 installed alone on Ubuntu 22.04). Install pip for that interpreter (see Installation), check that <that python> -m pip --version works, then restart Tegvia.

"using the previous dependencies"

The message reads Tegvia: dependency install failed (offline?); using the previous dependencies (<folder>). Once online, restart Tegvia (launcher, or the service's restart) to install the new set. It means Tegvia could not download the new dependencies (typically no network after an update), so it started with the previous complete set it had kept. Tegvia works normally in the meantime.

If the folder name is followed by , a legacy set installed without hash verification, the kept set comes from an older Tegvia version and was installed without hash verification. It stays in use as long as the failure is unrelated to integrity, but install the new set once you are online: that one is verified.

To install the new set, once you are online, restart Tegvia (standalone launcher, or restart for the service). If it keeps failing, read state/bootstrap.log in the data folder (see dependency install failed).

"dependency integrity check failed"

The message starts with Tegvia: dependency integrity check failed (pip reported a hash mismatch) (or, with a warning, Tegvia: SECURITY WARNING: dependency integrity check failed ...). A downloaded package did not match its expected fingerprint, so the new set of dependencies was not installed. This can come from a network that alters downloads or a faulty mirror.

Three possible outcomes:

  • A previous hash-verified set exists: Tegvia uses it and prints the security warning. It works, but without the update.
  • Only an older set installed without hash verification exists: Tegvia refuses it (the message says it is not used) and does not start.
  • No set is available: Tegvia does not start.

What to do: retry later from a trusted network (not public Wi-Fi or a proxy that inspects traffic), by restarting Tegvia (standalone launcher, or restart for the service). Read state/bootstrap.log in the data folder. If it keeps failing on a trusted network, report it.

Claude Code can no longer reach the API

settings.json redirects to 127.0.0.1:8736, but nothing answers.

  1. Run tegvia-service status, then start (or restart) if the service is stopped. Read proxy.stderr.log in the data folder: it says why the proxy stopped (see The proxy does not start).
  2. If you no longer want Tegvia: run ./uninstall.sh (uninstall.cmd on Windows), which restores settings.json.
  3. If Tegvia is no longer available at all, fix settings.json by hand: see Uninstall.

After an abrupt stop of the standalone launcher, see All Claude Code sessions fail after a standalone crash.

"This evaluation version of Tegvia expired": Tegvia will not start

Messages: This evaluation version of Tegvia expired on <date>, so it did not start. when starting, or the same message after install (install refused). The exit code is 78. The date is compared with your machine's clock: check it if the message seems premature. Claude Code has been put back on a direct connection, so it keeps working, without Tegvia. If the first line says the expiry date "is not valid", the archive is damaged: ask for a new copy.

A two-line message, without the "Claude Code has been put back on a direct connection" line, is normal for install --dry-run and for proxy.py without --configure. From the launcher, the service, install or proxy.py --configure, two lines mean the redirect could not be removed: ~/.claude/settings.json is unreadable, not valid or not writable. Check that file: while ANTHROPIC_BASE_URL still points at the proxy, Claude Code fails. See Uninstall.

What to do: get a new version from hello@tegvia.tech and follow Update. uninstall, stop and status still work. See Evaluation expiry.

"This evaluation version of Tegvia expired": install refused

install (and install --no-tray) on an expired version installs nothing: it removes the Tegvia redirect from ~/.claude/settings.json (Claude Code goes back to a direct connection), prints the same full message and exits with code 78. Only install --dry-run changes nothing at all, and its message has no "direct connection" line. Get a new version from hello@tegvia.tech and follow Update, then run install again.

Port 8736 is already in use

Tegvia treats the proxy as running as soon as something listens on the port. If another program holds it, requests go to that program.

  • Find which process listens on the service port (8736 by default, shown by status): ss -ltnp | grep <port> on Linux, lsof -nP -iTCP:<port> -sTCP:LISTEN on macOS, the LISTENING line of netstat -ano | findstr <port> on Windows. Then run tegvia-service status: if its Deployment: line reads service, standalone or manual, Tegvia holds the port; if it reads unknown, another program or an older Tegvia version still running holds it.
  • Stop the other program, or pick another port. For the background service, run install --port N (see Choosing the port); for a manual run, use TEGVIA_PORT.

macOS: the service is installed but never becomes active

install prints a warning like this when the Tegvia folder is in a folder that macOS protects (~/Downloads, ~/Documents, ~/Desktop, iCloud Drive):

service: warning: the Tegvia folder <folder> is inside <protected folder>, which macOS protects; the service started at login may be unable to read it. Move the folder (for example to ~/tegvia) and run install again.

Cause: the service started at login runs in the background and macOS may refuse it access to files in those folders. Fix: move the whole Tegvia folder to a plain location such as ~/tegvia, then run ./install.sh again from there. How exactly macOS refuses (silently or with a prompt) was not confirmed when this page was written.

A legitimate command is blocked

  1. Read the reason in the "TEGVIA Protection" notice.
  2. If the block is clearly a false positive, report it to your Tegvia administrator with the full message (it holds the session id and the command), or the matching excerpt of the session log.

An unexpected "Secret in context" alert

  • For a secret already removed: it is still in the history sent. Revoke it at its provider; a new conversation starts clean.
  • Coming back after a restart: expected, the memory of already-flagged secrets is lost (and a resumed session sends its history again).
  • False positive: copy the fingerprint (select it on the Alerts page), add it to SECRET_ALLOWLIST_FINGERPRINTS in ~/.tegvia/config.py and restart the proxy. Invalid entries are ignored with a warning giving their number (once per new invalid value), in proxy.stderr.log when the proxy writes log files (background launch or service), in the terminal for a foreground run.

An unexpected "Personal data in the context" alert

  • For data already removed: it is still in the history sent. Start a new conversation to start clean.
  • Coming back after a restart: expected, the memory of already-flagged findings is lost (and a resumed session sends its history again).
  • For your company's addresses: add the domain to PII_IGNORED_EMAIL_DOMAINS in ~/.tegvia/config.py, or raise PII_CONTACT_THRESHOLD, then restart the proxy.
  • A file you expected to be flagged was not: the number must satisfy its checksum, and emails or phone numbers need at least 10 distinct values in the same block.

Session blocked because of the downloads folder

Every request is refused with working directory is a downloads folder or session previously blocked: downloads folder. Claude Code was started in a downloads folder. Quit Claude Code, move only the files you need to a dedicated project folder outside your downloads folders (do not trust or copy any CLAUDE.md, or file it imports such as AGENTS.md, found in a downloads folder) and start it again from there.

A module seems inactive

Check it is not in the list of disabled modules. canary_token is disabled by default.

An update does not seem to apply

The running proxy keeps the old version. Restart Tegvia (restart for the service; see Update).

Getting more detail

TEGVIA_LOG_LEVEL is read from the environment only (not from config.py). With the background service on Linux, WSL or macOS, a variable set in your terminal does not reach the proxy: stop the service, run the standalone launcher with the variable set (TEGVIA_LOG_LEVEL=DEBUG sh launch/tegvia.sh), reproduce the problem, then read the terminal output. On Windows, set it with setx TEGVIA_LOG_LEVEL DEBUG and run the service's restart; the detail goes to proxy.stderr.log in the data folder.

Session logs

  • Requests work but nothing is logged: the database is locked by another program, on a read-only or full disk, or its folder is not writable. Logging never blocks requests: the log entries wait in tegvia.db.pending (same folder, up to 512 MiB) and the proxy retries every 30 seconds by itself. No restart is needed. Free space, fix permissions or close the program using the file; the log entries are then saved, in order and without duplicates, and the file disappears. Log entries are lost only if that file cannot be written either (full or read-only disk, unwritable folder) or has reached 512 MiB; Claude Code then shows "WARN Tegvia: log database unavailable and its backup file cannot be written: log entries are being lost." While the file is replayed it is renamed (tegvia.db.pending.<n> may appear briefly); a leftover ending in .done can be deleted. Messages you may see in proxy.stderr.log: "log database busy: items are kept in ... until it is writable", "cannot open log database", "N log item(s) remain in ... ; they are replayed once the database is writable", "replayed N pending log item(s) into the database", "N corrupt line(s) skipped while replaying" (harmless, one damaged entry), "pending log file full or unwritable: dropped N item(s)" (the 512 MiB limit was reached: entries are lost) and "log queue full: dropped N item(s)" (very heavy load).
  • A warning line appears in Claude Code, after "Protected by Tegvia" or alone: "INFO Tegvia: log database unavailable, N log entries waiting to reconnect." (or "1 log entry waiting to reconnect"), or "WARN Tegvia: log database unavailable and its backup file cannot be written: log entries are being lost." The log database cannot be written right now; see the previous item. The line disappears once logging is back to normal. While the database is unavailable the line can also appear alone, at the start of any text of the answer.
  • The console shows a warning card about the log database: the texts are "The log database is unavailable: {n} log entries pending, to be saved as soon as it is free.", "The log database is unavailable for now. New log entries are being held back." and "The log database comes from a newer version of Tegvia: {n} log entries pending. Update Tegvia." Same causes and fixes as above.
  • The console is empty and shows "Some data is missing": the database was upgraded by a newer Tegvia and you went back to an older one. Update Tegvia again; do not delete the database unless you accept losing the history. New entries stay in tegvia.db.pending meanwhile.
  • The data folder is on a Windows drive shared with WSL (/mnt/c/...): Tegvia then avoids the faster write-ahead mode, which is unreliable there, and uses the slower classic mode. Logging still works. Run the proxy and the console on the same side (see Windows and WSL see different data) and keep the data folder on a native Linux or Windows path if you can.
  • tegvia.db-wal and tegvia.db-shm files: normal while the proxy runs. Do not delete them; copy or move the database only with the proxy stopped.
  • A tegvia.db.bak-v<n> file appeared: it is the safety copy made before a database upgrade (done on the first logged request after the proxy starts). Delete it when everything works. If the upgrade failed (error in proxy.stderr.log), the copy is your original data. Like the database, it contains sensitive data.
  • A tegvia.db.pending file appeared: log entries are waiting for the database (see above). It is deleted once they are saved. On Linux and macOS it is readable by you only (on Windows it takes the folder's permissions) and contains the same sensitive data as the database.
  • The database keeps growing: nothing is purged. Stop the proxy, back up or delete tegvia.db.

Web console

  • 403 "Forbidden": the console only accepts the addresses http://127.0.0.1:<port>/tegvia/ui/ and http://localhost:<port>/tegvia/ui/ (with the right port). Another host name or address, for example the machine's network name, is refused.
  • Blank page: check the proxy is running (tegvia-service status) and that you are using the right port, then reload the page. The console needs JavaScript. A "This page could not be loaded" message with a "Try again" button means the data could not be read: check the proxy, then retry.
  • "Proxy unreachable" in the status card: the proxy does not answer on its port. The console is served by the proxy, so it cannot load data while the proxy is stopped. Start Tegvia (service or launcher), then reload the page. The message can also appear in a page that was already open.
  • "Nothing to show yet": no request has gone through Tegvia yet, or TEGVIA_HOME, TEGVIA_LOG_DIR or TEGVIA_LOG_DB points elsewhere than the proxy's database (see Windows and WSL see different data).
  • "Some data is missing": the database comes from a newer version of Tegvia, or could not be read in full. The affected screens show "Some data is missing: the log database could not be read in full, or it holds log entries written by a newer version of Tegvia. The rest is shown below." No count is given. If the database comes from a newer version, update Tegvia.
  • The Tools page shows "No tool call in this period": no tool call was recorded in the chosen period. Right after installation the tools offered to Claude Code are already listed with 0 calls, and MCP servers show as "never used" until they are first called. Wait for some usage, and check with "All" before deciding.
  • Declared tools or MCP servers are missing on the Tools page: the tools offered to the model are read from the recorded requests. If that data is unreadable or too large, it is ignored and a warning is written to proxy.stderr.log. Likewise, beyond 4096 tool names in a single set of declared tools, the extra names are ignored with a warning. Calls are still counted; only the "declared" figures and the "never used" servers are incomplete.
  • The data does not move: the console does not update by itself, click "Refresh".
  • "The documentation is not built" (404 page after clicking "Documentation" or opening /tegvia/docs/): this only happens in a development checkout, because the distributed archive ships the documentation already built. From the repository root, run uv pip install --python .venv -r requirements-docs.txt then .venv/bin/python scripts/build_console_docs.py (.venv\Scripts\python.exe on Windows), and reload the page.

Settings and protection

  • "Database unusable at startup" (Settings page read-only, or settings_defect in /tegvia/status): at startup the log database could not be created, opened or read, stayed locked too long, or comes from a newer version of Tegvia. The proxy then uses the config.py values and keeps protection active. Look for "settings store unusable" in proxy.stderr.log (see Useful files), check the permissions on the data folder and that no other program locks tegvia.db, or update Tegvia if the database is newer. Then restart Tegvia. A merely missing database is not a defect: it is created.
  • The "Protection disabled since …" banner shows: protection was paused from the console (by you, or by someone or an agent with access to your computer: look for the "Setting changed" event in the Alerts). Click "Re-enable protection", then open a new Claude Code session. While paused, a proxy started by the service or the launcher removes the redirect from settings.json and does not point it again, so sessions go directly to the API.
  • A settings.json warning ("settings.json could not be restored" or "settings.json could not be updated"): shown when the proxy was launched by the service, the standalone launcher or by hand with --configure. Protection did change, but Claude Code's settings file is unreadable, is not valid JSON or cannot be modified. Fix it (the message gives the reason), then restart Tegvia. As long as settings.json points at the proxy, Claude Code goes through it, and it relays without inspecting if protection is paused.
  • Protection is re-enabled but nothing is inspected: only new sessions go through Tegvia again. Open a new session or restart Claude Code.
  • "Value rejected: …" when saving: a value breaks the rules. Nothing was saved; fix the field shown.
  • "Request refused: unrecognised origin. Reload the page. Nothing was saved.": the console only accepts writes from http://127.0.0.1:<port>/tegvia/ui/ or http://localhost:<port>/tegvia/ui/. Reload the page at that address.
  • "The proxy is not responding. Nothing changed.": start Tegvia (see The proxy does not start), then try again.
  • My config.py change has no effect: a value saved from the console wins over config.py. Use "Restore" on the Settings page, then save.
  • An agent call is blocked by settings_tamper_check: the agent aimed at the settings routes or Tegvia's database. Make the change yourself from the console.

Windows and WSL see different data

Under WSL, ~ is the Linux home folder, so ~/.tegvia is not the .tegvia folder in your Windows profile. A proxy running under Windows and the console, tegvia-service status or the logs read from WSL therefore look at two different data folders and databases: they show no data, or a proxy that "does not run", although the proxy works. To make them agree, run the proxy, the web console and the service commands on the same side: all in WSL, or all in Windows. Each side has its own data folder and its own database, and they are not meant to be shared.

Do not point TEGVIA_HOME or TEGVIA_LOG_DB at the same folder or file on both sides. A data folder on a Windows drive (/mnt/c/...) must not be shared by proxies on both sides, and it cannot hold a config.py on the WSL side: every file there looks writable by everyone, so the file is refused.

All Claude Code sessions fail after a standalone crash

If the standalone launcher was killed brutally (kill -9, taskkill /F without /T), the proxy keeps running and Claude Code still goes through it, but relaunching is refused with the "port 8736 is already in use" message. If the power was cut instead, the proxy is gone and settings.json still redirects to it, so every session fails to reach the API.

  • Proxy still running: find its <pid> with lsof -nP -iTCP:8736 -sTCP:LISTEN (Linux, macOS) or netstat -ano | findstr 8736 (Windows, last column of the LISTENING line). Ignore the other lines: they are client connections, Claude Code's among them, and killing them does not free the port. On Linux and macOS, stop it with kill <pid> (a plain SIGTERM, which also removes the redirect). On Windows, use Task Manager (End task) or taskkill /F /PID <pid>; this forced stop does not remove the redirect, the relaunch does. Then relaunch (launch/tegvia.sh, tegvia.command or tegvia.cmd).
  • Power cut: relaunch the launcher; it removes the leftover redirect (Tegvia: previous redirection left by an abrupt stop removed.) and starts normally. Stop it with Ctrl-C to leave Claude Code without a redirect.
  • Or repair settings.json by hand: see Repair after an abrupt stop.

If the launcher refuses to start, see Refusals.

Install failed or the tray icon did not appear

Open state/install.log in the data folder (~/.tegvia/state/install.log, or %USERPROFILE%\.tegvia\state\install.log on Windows; the summary line of the install output gives the path). It holds everything install printed, in blocks, the newest at the end, and no secrets. For a dependency failure, also read state/bootstrap.log.

  • Installation failed (see above).: the reason is printed just above that line and in install.log.
  • Tegvia installed, but the tray icon reported a problem (see above).: the service works; read the Tray icon: line above it. If it says autostart entry installed, but the icon could not be started now, the icon appears at your next login. On the default port (8736) you can start it now with launch\tegvia-tray.cmd (Windows) or sh launch/tegvia-tray.sh (Linux). On another installed port the manual launcher would use 8736: the icon starts at your next login, or run install again.
  • Tray icon started.: the icon was launched right away; nothing to do.
  • The icon crashed later: an unexpected error is now written to state/tray.log before the icon exits.
  • The window closed before I could read it (Windows): install.cmd waits for Enter when started in a console; otherwise read install.log.

Background service

Start with sh launch/tegvia-service.sh status (launch\tegvia-service.cmd status on Windows): it shows the state, the log paths and the end of proxy.stderr.log. See Background service.

  • systemd unusable (Linux, WSL): install writes nothing and prints why. On WSL, add [boot] / systemd=true to /etc/wsl.conf, run wsl --shutdown and retry. See WSL.
  • Port in use: another program listens on the service port (8736 by default, shown by status). Find it (lsof -nP -iTCP:<port> -sTCP:LISTEN, or netstat -ano | findstr <port> on Windows), stop it, then run start; or move the service to a free port with install --port N. See Port already in use. The service removes any leftover redirect first, so new sessions go directly to the API.
  • install refuses a path: the Python or Tegvia folder path is relative (or, on Windows, contains % or "). Use an absolute path.
  • install refuses: --port and TEGVIA_PORT differ (exit code 3): the message names both values. Remove TEGVIA_PORT or give the same value to --port, then run install again.
  • install refuses an invalid port (exit code 2): --port must be a whole number from 1024 to 65535. Fix it and run install again.
  • "was not generated by Tegvia": a file or task with the same name exists without Tegvia's marker. Tegvia refuses to overwrite it; rename or remove it yourself.
  • status says the interpreter or folder no longer exists: the Tegvia folder or Python was moved or removed. Run install again.
  • Windows refuses a path (% or "): move Tegvia or use another Python. TEGVIA_HOME refused: run setx TEGVIA_HOME "<folder>", open a new window (or double-click install.cmd), then run install.cmd.
  • Sessions bypass Tegvia for a few seconds after a restart: expected, see the restart window.

System tray icon

The icon never shows an error dialog; when it cannot run it prints the reason and exits with code 3. On Linux and macOS, launch it by hand to read the reason (sh launch/tegvia-tray.sh). On Windows the launcher starts the icon detached and prints nothing: the reason is in %USERPROFILE%\.tegvia\state\tray.log. That file (~/.tegvia/state/tray.log) works everywhere; launch/tegvia-service.sh status prints an Icon: line. See System tray icon.

  • No icon on Linux, "No system tray found": a desktop without a StatusNotifier host, typically GNOME. Install and enable the AppIndicator and KStatusNotifierItem Support extension, log out and back in, then run install again (or the manual launcher).
  • No icon, "No graphical session": neither DISPLAY nor WAYLAND_DISPLAY is set (SSH, console login). Start it from your desktop session.
  • Exit code 3 on WSL: WSL has no tray. Run launch\tegvia-tray.cmd on the Windows side.
  • Exit code 3, "not supported": unsupported system or architecture (Linux x86_64, aarch64 and riscv64, macOS 11+, Windows 10/11 only).
  • "the tray icon dependencies could not be installed" (Linux, macOS): you are offline, or requirements-tray.txt is missing from your copy of Tegvia (a damaged or incomplete copy). Go online and run again; if the file is missing, get a complete copy (see Installation from an archive). The proxy is not affected.
  • Windows: the icon is missing: look behind the ^ arrow and drag it onto the taskbar.
  • install printed "Tray icon: ... leaving it alone": an entry with the same name exists and Tegvia did not create it. It is never overwritten: rename or remove it yourself and run install again.
  • The icon disappeared after I quit it: it is not relaunched automatically; start it by hand, or log in again. Quit Tegvia also stopped Tegvia (when the service is installed): launching the icon starts it again.
  • The icon shows Error ("Tegvia: could not start (code N)"): Tegvia could not start. The code is the exit code of the start command (usually 1; it is not always 78), and one "Service action failed" notification shows it. Read state/tray.log and proxy.stderr.log for the cause (port already in use, invalid settings.json, invalid config.py...), fix it, then choose Service > Start in the icon menu; the icon returns to normal as soon as Tegvia answers. On Windows the task is retried up to 3 times, 1 minute apart. On Linux and macOS, when the system accepted the start but Tegvia then failed (for example port busy), the icon shows Stopped, not Error: check the same logs, then use Service > Start.
  • "Tegvia icon is already running.": a single icon is allowed; use the existing one. This message is printed in the terminal on Linux and macOS only; on Windows a second launch exits silently and the message is written to tray.log.
  • Icon shows Stopped but Claude Code works: the icon waits for two failed checks; if the proxy runs, check that the icon and the proxy use the same port and data folder (TEGVIA_PORT, TEGVIA_HOME).
  • No block notification: check Notifications in the icon menu, your system's Do Not Disturb, and that the blocked item is a block (warnings are off by default).
  • macOS notification from "Script Editor": expected.
  • No Service entry in the menu: the service is not installed on this machine, or the icon runs against a WSL proxy from Windows.
  • I do not want the icon: install --no-tray installs the service without the icon, but it does not remove an icon entry that already exists, and uninstall removes the whole service, not only the icon. To keep the service and drop the icon, either run uninstall then install --no-tray, or remove the autostart entry by hand and quit the icon (Quit Tegvia in its menu, which also stops the service: run start afterwards):
    • Linux: delete ~/.config/autostart/io.tegvia.tray.desktop.
    • macOS: run launchctl bootout gui/$(id -u)/io.tegvia.tray, then delete ~/Library/LaunchAgents/io.tegvia.tray.plist.
    • Windows: delete the Tegvia value under HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run (for example reg delete HKCU\Software\Microsoft\Windows\CurrentVersion\Run /v Tegvia /f).