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: ...: yourconfig.pyhas a mistake on that line. Fix it, or remove or rename the file.tegvia: refusing to run .../config.py: not owned by the current userorwritable 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 theTEGVIA_HOMEfolder) or fix its ownership. The proxy exits before readingconfig.pyand 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.login 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
outcomeof 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.
- Did you just install or start Tegvia? Restart Claude Code: a session already open keeps the address it read at its start.
tegvia-service statussays the service is not active, or thatsettings.jsonis not redirected → runstart(service) or start the standalone launcher, then restart Claude Code. Check that noANTHROPIC_BASE_URLset elsewhere (shell environment variable, project settings.claude/settings.json) takes precedence.- 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.
- Run
tegvia-service status, thenstart(orrestart) if the service is stopped. Readproxy.stderr.login the data folder: it says why the proxy stopped (see The proxy does not start). - If you no longer want Tegvia: run
./uninstall.sh(uninstall.cmdon Windows), which restoressettings.json. - If Tegvia is no longer available at all, fix
settings.jsonby 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:LISTENon macOS, theLISTENINGline ofnetstat -ano | findstr <port>on Windows. Then runtegvia-service status: if itsDeployment:line readsservice,standaloneormanual, Tegvia holds the port; if it readsunknown, 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, useTEGVIA_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¶
- Read the reason in the "TEGVIA Protection" notice.
- 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_FINGERPRINTSin~/.tegvia/config.pyand restart the proxy. Invalid entries are ignored with a warning giving their number (once per new invalid value), inproxy.stderr.logwhen 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_DOMAINSin~/.tegvia/config.py, or raisePII_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.donecan be deleted. Messages you may see inproxy.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.pendingmeanwhile. - 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-walandtegvia.db-shmfiles: 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 inproxy.stderr.log), the copy is your original data. Like the database, it contains sensitive data. - A
tegvia.db.pendingfile 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/andhttp://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_DIRorTEGVIA_LOG_DBpoints 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, runuv pip install --python .venv -r requirements-docs.txtthen.venv/bin/python scripts/build_console_docs.py(.venv\Scripts\python.exeon Windows), and reload the page.
Settings and protection¶
- "Database unusable at startup" (Settings page read-only, or
settings_defectin/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 theconfig.pyvalues and keeps protection active. Look for "settings store unusable" inproxy.stderr.log(see Useful files), check the permissions on the data folder and that no other program lockstegvia.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.jsonand does not point it again, so sessions go directly to the API. - A
settings.jsonwarning ("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 assettings.jsonpoints 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/orhttp://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.pychange has no effect: a value saved from the console wins overconfig.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>withlsof -nP -iTCP:8736 -sTCP:LISTEN(Linux, macOS) ornetstat -ano | findstr 8736(Windows, last column of theLISTENINGline). 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 withkill <pid>(a plain SIGTERM, which also removes the redirect). On Windows, use Task Manager (End task) ortaskkill /F /PID <pid>; this forced stop does not remove the redirect, the relaunch does. Then relaunch (launch/tegvia.sh,tegvia.commandortegvia.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.jsonby 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 ininstall.log.Tegvia installed, but the tray icon reported a problem (see above).: the service works; read theTray icon:line above it. If it saysautostart 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 withlaunch\tegvia-tray.cmd(Windows) orsh launch/tegvia-tray.sh(Linux). On another installed port the manual launcher would use 8736: the icon starts at your next login, or runinstallagain.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.logbefore the icon exits. - The window closed before I could read it (Windows):
install.cmdwaits for Enter when started in a console; otherwise readinstall.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):
installwrites nothing and prints why. On WSL, add[boot]/systemd=trueto/etc/wsl.conf, runwsl --shutdownand 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, ornetstat -ano | findstr <port>on Windows), stop it, then runstart; or move the service to a free port withinstall --port N. See Port already in use. The service removes any leftover redirect first, so new sessions go directly to the API. installrefuses a path: the Python or Tegvia folder path is relative (or, on Windows, contains%or"). Use an absolute path.installrefuses:--portandTEGVIA_PORTdiffer (exit code 3): the message names both values. RemoveTEGVIA_PORTor give the same value to--port, then runinstallagain.installrefuses an invalid port (exit code 2):--portmust be a whole number from 1024 to 65535. Fix it and runinstallagain.- "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.
statussays the interpreter or folder no longer exists: the Tegvia folder or Python was moved or removed. Runinstallagain.- Windows refuses a path (
%or"): move Tegvia or use another Python.TEGVIA_HOMErefused: runsetx TEGVIA_HOME "<folder>", open a new window (or double-clickinstall.cmd), then runinstall.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
installagain (or the manual launcher). - No icon, "No graphical session": neither
DISPLAYnorWAYLAND_DISPLAYis set (SSH, console login). Start it from your desktop session. - Exit code 3 on WSL: WSL has no tray. Run
launch\tegvia-tray.cmdon 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.txtis 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.
installprinted "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 runinstallagain.- 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.logandproxy.stderr.logfor the cause (port already in use, invalidsettings.json, invalidconfig.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-trayinstalls the service without the icon, but it does not remove an icon entry that already exists, anduninstallremoves the whole service, not only the icon. To keep the service and drop the icon, either rununinstalltheninstall --no-tray, or remove the autostart entry by hand and quit the icon (Quit Tegvia in its menu, which also stops the service: runstartafterwards):- 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
Tegviavalue underHKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run(for examplereg delete HKCU\Software\Microsoft\Windows\CurrentVersion\Run /v Tegvia /f).
- Linux: delete