Dépannage¶
Commencez toujours par l'état du service en arrière-plan :
sh launch/tegvia-service.sh status
(launch\tegvia-service.cmd status sous Windows). Il indique si le service
est actif, si settings.json pointe vers le proxy, l'adresse de la console,
les chemins des journaux et, quand rien n'écoute sur le port, la fin de
proxy.stderr.log. Voir Service en arrière-plan. Si vous
utilisez le lanceur autonome, lisez plutôt les
messages affichés dans son terminal.
« Redémarrer Tegvia » signifie ci-dessous : restart pour le service (voir
Service en arrière-plan), ou arrêter le lanceur autonome avec
Ctrl-C puis le relancer.
Fichiers utiles¶
Dans le dossier de données de Tegvia (~/.tegvia, ou le dossier défini par
TEGVIA_HOME).
tegvia-service status affiche les chemins des deux journaux du proxy, qui
se trouvent dans ce dossier :
| Fichier | Contenu |
|---|---|
state/install.log |
Ce que install / uninstall ont affiché, exécution après exécution (aucun secret). |
state/tray.log |
Journal de l'icône, y compris ses plantages. |
state/bootstrap.log |
Installation des dépendances (erreurs pip). |
proxy.stderr.log |
Journal applicatif du proxy démarré par le service ou en arrière-plan (erreurs, appels d'outils) et raison d'un échec de démarrage. |
proxy.stdout.log |
Autres sorties simples de ce proxy (bandeau de démarrage). |
tegvia.db |
Base des journaux de session (voir Utilisation). |
tegvia.db-wal, tegvia.db-shm |
Fichiers annexes normaux de la base pendant que le proxy tourne. |
tegvia.db.bak-v<n> |
Copie faite avant une mise à niveau de la base ; supprimable quand tout fonctionne. |
tegvia.db.pending |
Entrées de journal en attente d'enregistrement quand la base est indisponible ; supprimé automatiquement une fois enregistrées. |
Les deux fichiers proxy.*.log ne sont écrits que pour un proxy démarré par
le service ou par le mode arrière-plan du lanceur (pas pour un proxy lancé à
la main, ni pour le lanceur au premier plan, dont la sortie reste dans le
terminal). Ils ne sont lisibles que par vous (Linux, WSL, macOS) et restent
de taille limitée : chacun est plafonné à 10 Mio. Quand il est plein, il
devient .1 (par exemple proxy.stderr.log.1), l'ancien .1 devient .2,
puis .3, et le plus ancien est supprimé : 4 fichiers au plus par journal,
sans ligne perdue ni coupée en deux. Les en-têtes d'identifiants
(x-api-key, Authorization) y sont tronqués comme partout ailleurs.
Le proxy ne démarre pas¶
Lancez tegvia-service status. Si le proxy n'écoute pas, la commande affiche
les chemins des deux journaux (dans le dossier de données) et montre la fin de
proxy.stderr.log, qui contient les erreurs survenues après le démarrage et
les refus pour port occupé ou settings.json invalide. Les échecs plus
précoces (config.py cassé, dossier de données refusé, Python trop ancien)
n'y sont pas écrits. Pour les diagnostiquer, lancez le lanceur autonome dans
un terminal : le message s'y affiche. Sous le service, sous Linux/WSL ils
sont dans le journal utilisateur (journalctl --user -u tegvia.service) ;
sous macOS et Windows aucune copie n'est conservée, lancez donc le lanceur
dans un terminal. Messages typiques :
tegvia: error in .../config.py, line N: ...: votreconfig.pycontient une erreur à cette ligne. Corrigez-la, ou supprimez ou renommez le fichier.tegvia: refusing to run .../config.py: not owned by the current userouwritable by group or others: corrigez les permissions (chmod 600, et le fichier doit vous appartenir) ou supprimez le fichier. Il n'est pas exécuté tant que ce n'est pas fait.- Le dossier de données est refusé (il ne vous appartient pas, ou il est
modifiable par le groupe ou les autres, sous Linux, WSL, macOS) : lancez
chmod go-w ~/.tegvia(ou sur le dossierTEGVIA_HOME) ou rectifiez son propriétaire. Le proxy s'arrête avant de lireconfig.pyet rien n'est écrit dans ce dossier d'ici là. - Un message indiquant que le port est déjà utilisé : voir Le port 8736 est déjà utilisé.
Python X.Y.Z found, but Python 3.11 or newer is required: le proxy a été lancé par un Python trop ancien. Installez Python 3.11 ou plus récent (Installation), puis redémarrez Tegvia.- Une dépendance manquante ou une erreur d'import : voir « dependency install failed ».
Une fois corrigé, redémarrez Tegvia. Si le journal ne montre aucune ligne de ce genre, le proxy n'a peut-être encore rien écrit. Si les fichiers de journal de sortie du proxy ne peuvent pas être écrits, par exemple parce qu'un lien symbolique se trouve à leur nom, il n'est pas suivi : le proxy se rabat sur autre chose ou l'écriture échoue.
Une erreur de configuration (port occupé, settings.json illisible,
config.py cassé) n'est pas relancée par le service sous Linux, WSL et
macOS : corrigez la cause, puis lancez start. Sous Windows, le Planificateur
de tâches réessaie jusqu'à 3 fois (voir
Service en arrière-plan).
Claude Code affiche API Error 500, 502 ou 504 avec un message Tegvia¶
Quand quelque chose se passe mal entre Claude Code et l'API, Tegvia répond
par une erreur dont le texte commence par Tegvia: plutôt que par un échec
brut. Exemple :
API Error: 502 {"type":"error","error":{"type":"api_error","message":"Tegvia: could not reach the Anthropic API (ClientConnectorError) (request 3fa9c1d2)."}}
Le message contient un identifiant de requête (8 caractères hexadécimaux) qui désigne l'échange. Signification de chaque cas (le texte du message est en anglais) :
- 500, « internal error before sending the request upstream » : Tegvia a échoué avant l'envoi. Rien n'a été envoyé à Anthropic.
- 500, « error while handling the Anthropic response » : Tegvia a échoué en traitant la réponse. La réponse n'a pas été transmise.
- 502, « could not reach the Anthropic API » : l'API est injoignable (réseau, DNS, TLS) ou la connexion a été coupée.
- 504, « the Anthropic API timed out » : l'API n'a pas répondu à temps (voir les délais ci-dessous).
Quand la réponse est déjà en cours de streaming, le statut reste celui de l'API et la même erreur arrive sous forme d'un dernier événement d'erreur, après le texte déjà affiché. Claude Code relance lui-même les erreurs 5xx : une erreur ponctuelle disparaît souvent seule.
Où lire le détail :
proxy.stderr.logdans le dossier de données : un avertissement avec l'identifiant de requête, l'étape et le type d'exception (voir Obtenir plus de détails pour la trace complète) ;- la console web : la valeur
outcomede l'échange (error_before_sending,upstream_error,error_response), et la page des flux sortants.
Pour un 504, ou une réponse coupée après un long silence, augmentez
UPSTREAM_READ_TIMEOUT_SECONDS dans votre
config.py (600 s par défaut, silence maximal
entre deux morceaux de données ; il n'y a pas de limite totale) et, si la
connexion elle-même est lente à s'ouvrir, UPSTREAM_CONNECT_TIMEOUT_SECONDS
(30 s par défaut). Redémarrez ensuite Tegvia.
Note
Un échange enregistré comme client_closed n'est pas une panne : Claude
Code a fermé la connexion avant la fin de la réponse, par exemple quand
vous avez appuyé sur Échap.
Erreur se terminant par SSEEventTooLarge¶
Si le message indique « error while handling the Anthropic response
(SSEEventTooLarge) », Tegvia a reçu un seul événement de streaming de plus
de 16 Mio. Cela n'arrive qu'avec une cible autre que l'API Anthropic (une
passerelle définie par TEGVIA_TARGET ou par son réglage dans la console) qui
envoie un tel événement. La limite est fixe et ne peut pas être modifiée.
Consultez proxy.stderr.log et la valeur error_response de outcome dans
la console, puis vérifiez le comportement de streaming de la passerelle.
Erreur se terminant par SSEFramingError¶
Si le message indique « error while handling the Anthropic response
(SSEFramingError) », Tegvia a reçu un flux de streaming dont une ligne,
autre que la toute première du flux, commence par une marque d'ordre des
octets UTF-8 (BOM, octets EF BB BF). Claude Code retire cette marque au
début de chaque ligne alors que le standard SSE ne la retire qu'au début du
flux : un tel flux pourrait faire passer un appel d'outil sans que les
contrôles de Tegvia le voient, donc Tegvia le refuse et interrompt la
réponse. Cela n'arrive qu'avec une cible autre que l'API Anthropic (une
passerelle définie par TEGVIA_TARGET ou par son réglage dans la console) ou un intermédiaire qui modifie le
flux. Consultez proxy.stderr.log et la valeur error_response de
outcome dans la console, puis corrigez la passerelle pour
qu'elle n'insère pas de BOM au milieu du flux.
Avertissement « stream ended inside an SSE event, N bytes dropped »¶
Cet avertissement dans proxy.stderr.log signifie que le flux amont s'est
arrêté au milieu d'un événement (réponse amont tronquée ou malformée). La
partie incomplète (N octets) n'est pas transmise à Claude Code. La valeur outcome de
l'échange reste relayed. Il n'est pas écrit quand Tegvia a lui-même coupé
le flux, que le flux a échoué ou que Claude Code a fermé la connexion.
Les réponses ne commencent pas par « Protected by Tegvia »¶
La session ne passe pas par le proxy.
Le filigrane n'est attendu que sur le premier texte de chaque réponse (après chaque question posée), pas sur chaque texte entre deux appels d'outils : l'absence de filigrane sur un texte situé après un appel d'outil est normale. Le filigrane peut aussi manquer quand le tour commence par un sous-agent ou une requête auxiliaire : il a pu aller sur ce texte plutôt que sur la réponse visible.
- Vous venez d'installer ou de démarrer Tegvia ? Redémarrez Claude Code : une session déjà ouverte garde l'adresse lue à son démarrage.
tegvia-service statusindique que le service n'est pas actif, ou quesettings.jsonn'est pas redirigé → lancezstart(service) ou démarrez le lanceur autonome, puis redémarrez Claude Code. Vérifiez qu'aucunANTHROPIC_BASE_URLdéfini ailleurs (variable d'environnement du shell, réglages du projet.claude/settings.json) ne prend le dessus.- La protection a été mise en pause depuis la console : voir la section Réglages et protection.
« no usable system Python 3.11+ found on PATH »¶
Le message complet (en anglais) est :
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.
Aucun Python 3.11+ utilisable n'a été trouvé, pas même un 3.10 (sinon voir
la section suivante). Installez-le en suivant
Installation, vérifiez qu'il est dans le PATH, puis
relancez la commande. Les Python situés dans un .venv sont volontairement
ignorés.
Windows — Smart App Control : les copies de python.exe dans un
environnement virtuel peuvent être bloquées par la politique de sécurité de
Windows. Tegvia les évite exprès : installez un Python « système » depuis
python.org.
Python trop ancien : Tegvia ne démarre pas¶
Tegvia a trouvé un Python 3.10 mais aucun 3.11 ou plus récent. Il ne peut pas fonctionner. L'installation, les commandes du service ou le lanceur s'arrêtent avec le code de sortie 1 et affichent un message comme celui-ci (en anglais ; la version et le chemin sont ceux de votre 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.
Ce message ne modifie rien sur votre machine. Claude Code continue de fonctionner, mais sans Tegvia si celui-ci ne tournait pas.
Que faire : installez Python 3.11 ou plus récent
(Installation), puis relancez la commande (install,
start ou restart pour le service, ou le lanceur).
« dependency install failed »¶
L'installation des dépendances a échoué. Consultez state/bootstrap.log dans le dossier de données.
Causes fréquentes : pas d'accès à PyPI (proxy d'entreprise : configurez
pip), espace disque, version de Python trop ancienne. Corrigez, puis
redémarrez Tegvia.
Si le message commence plutôt par Tegvia: pip is not available for, suivi
du chemin d'un Python, ce Python n'a pas de pip (cas typique d'un
python3.11 installé seul sur Ubuntu 22.04). Installez pip pour cet
interpréteur (voir Installation), vérifiez que
<ce python> -m pip --version fonctionne, puis redémarrez Tegvia.
« using the previous dependencies »¶
Le message est Tegvia: dependency install failed (offline?); using the
previous dependencies (<dossier>). Once online, restart Tegvia (launcher, or
the service's restart) to install the new set. Il signifie que Tegvia n'a
pas pu télécharger les nouvelles dépendances (typiquement pas de réseau après
une mise à jour) et a démarré avec le dernier ensemble complet qu'il avait
conservé. Tegvia fonctionne normalement en attendant.
Si le nom du dossier est suivi de , a legacy set installed without hash
verification, l'ensemble conservé date d'une ancienne version de Tegvia et a
été installé sans vérification d'empreintes. Il reste utilisé tant que l'échec
n'a aucun rapport avec l'intégrité, mais installez le nouvel ensemble une fois
en ligne : il est, lui, vérifié.
Pour installer le nouvel ensemble, une fois en ligne, redémarrez Tegvia
(lanceur autonome, ou restart pour le service). Si l'échec persiste,
consultez state/bootstrap.log dans le dossier de données (voir
« dependency install failed »).
« dependency integrity check failed »¶
Le message commence par Tegvia: dependency integrity check failed (pip
reported a hash mismatch) (ou, avec SECURITY WARNING:, Tegvia: SECURITY
WARNING: dependency integrity check failed ...). Un paquet téléchargé ne
correspondait pas à son empreinte attendue : le nouvel ensemble de
dépendances n'a pas été installé. Cela peut venir d'un réseau qui altère
les téléchargements ou d'un miroir défaillant.
Trois issues possibles :
- Un ensemble précédent vérifié existe : Tegvia l'utilise et affiche l'avertissement de sécurité. Il fonctionne, mais sans la mise à jour.
- Seul un ancien ensemble installé sans vérification d'empreintes existe : Tegvia le refuse (le message précise qu'il n'est pas utilisé) et ne démarre pas.
- Aucun ensemble n'est disponible : Tegvia ne démarre pas.
Que faire : réessayez plus tard, depuis un réseau de confiance (pas un Wi-Fi
public ni un proxy qui inspecte le trafic), en redémarrant Tegvia (lanceur
autonome, ou restart pour le service). Consultez state/bootstrap.log dans
le dossier de données. Si l'échec persiste sur un réseau de confiance,
signalez-le.
Claude Code n'arrive plus à joindre l'API¶
settings.json redirige vers 127.0.0.1:8736, mais rien ne répond.
- Lancez
tegvia-service status, puisstart(ourestart) si le service est arrêté. Consultezproxy.stderr.logdans le dossier de données : il indique pourquoi le proxy s'est arrêté (voir Le proxy ne démarre pas). - Si vous ne voulez plus de Tegvia : lancez
./uninstall.sh(uninstall.cmdsous Windows), qui restauresettings.json. - Si Tegvia n'est plus du tout disponible, réparez
settings.jsonà la main : voir Désinstallation.
Après un arrêt brutal du lanceur autonome, voir Toutes les sessions Claude Code échouent après un plantage autonome.
« Cette version d'évaluation de Tegvia a expiré » : Tegvia ne démarre pas¶
Messages : Cette version d'évaluation de Tegvia a expiré le <date>, elle ne
démarre donc pas. au démarrage, ou le même message après install
(installation refusée). Le code de sortie est 78. La date est comparée à
l'horloge de votre machine : vérifiez-la si le message semble prématuré. Claude
Code a été remis en connexion directe, il continue donc de fonctionner, sans
Tegvia. Si la première ligne dit que la date d'expiration « n'est pas valide »,
l'archive est abîmée : demandez-en une nouvelle copie.
Un message de deux lignes, sans la ligne « Claude Code a été remis en
connexion directe », est normal pour install --dry-run et pour proxy.py
sans --configure. Depuis le lanceur, le service, install ou proxy.py
--configure, deux lignes signifient que la redirection n'a pas pu être
retirée : ~/.claude/settings.json est illisible, invalide ou non modifiable.
Vérifiez ce
fichier : tant que ANTHROPIC_BASE_URL pointe vers le proxy, Claude Code échoue. Voir
Désinstaller.
Que faire : obtenez une nouvelle version auprès de hello@tegvia.tech et
suivez Mettre à jour. uninstall, stop et
status fonctionnent toujours. Voir Expiration de la version
d'évaluation.
« Cette version d'évaluation de Tegvia a expiré » : installation refusée¶
install (et install --no-tray) sur une version expirée n'installe rien : il
retire la redirection Tegvia de ~/.claude/settings.json (Claude Code repasse
en connexion directe), affiche le message complet et se termine avec le code
78. Seul install --dry-run ne modifie rien du tout, et son message n'a pas la
ligne « connexion directe ». Obtenez une nouvelle version auprès de hello@tegvia.tech,
suivez Mettre à jour, puis relancez
install.
Le port 8736 est déjà utilisé¶
Tegvia considère que le proxy tourne dès que quelque chose écoute sur le port. Si un autre programme l'occupe, les requêtes partent vers lui.
- Trouvez quel processus écoute sur le port du service (8736 par défaut,
affiché par
status) :ss -ltnp | grep <port>sous Linux,lsof -nP -iTCP:<port> -sTCP:LISTENsous macOS, la ligneLISTENINGdenetstat -ano | findstr <port>sous Windows. Lancez ensuitetegvia-service status: si sa ligneDeployment:indiqueservice,standaloneoumanual, c'est Tegvia qui occupe le port ; si elle indiqueunknown, c'est un autre programme ou une ancienne version de Tegvia encore en cours d'exécution. - Arrêtez l'autre programme, ou choisissez un autre port. Pour le service en
arrière-plan, lancez
install --port N(voir Choisir le port) ; pour un lancement manuel, utilisezTEGVIA_PORT.
macOS : le service est installé mais ne devient jamais actif¶
install affiche un avertissement de ce type quand le dossier Tegvia se
trouve dans un dossier que macOS protège (~/Downloads, ~/Documents,
~/Desktop, iCloud Drive) :
service: warning: the Tegvia folder <dossier> is inside <dossier protégé>, 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 : le service démarré à la connexion tourne en arrière-plan et macOS
peut lui refuser l'accès aux fichiers de ces dossiers. Solution : déplacez
tout le dossier Tegvia vers un emplacement ordinaire comme ~/tegvia, puis
relancez ./install.sh depuis celui-ci. Le comportement exact de macOS
(refus silencieux ou invite) n'était pas confirmé à la rédaction de cette
page.
Une commande légitime est bloquée¶
- Lisez la raison dans l'encadré « TEGVIA Protection ».
- Si le blocage est clairement un faux positif, signalez-le à votre administrateur Tegvia en joignant le message complet (il contient l'identifiant de session et la commande), ou l'extrait correspondant du journal de session.
Une alerte « Secret dans le contexte » inattendue¶
- Pour un secret déjà retiré : il est encore dans l'historique envoyé. Révoquez-le chez son fournisseur ; une nouvelle conversation repart propre.
- Qui revient après un redémarrage : normal, la mémoire des secrets déjà signalés est perdue (et une session reprise renvoie son historique).
- Faux positif : copiez l'empreinte (sélectionnez-la dans la page
Alertes), ajoutez-la à
SECRET_ALLOWLIST_FINGERPRINTSdans~/.tegvia/config.pyet redémarrez le proxy. Les entrées invalides sont ignorées avec un avertissement indiquant leur nombre (une fois par nouvelle valeur invalide), dansproxy.stderr.logquand le proxy écrit des fichiers journaux (lancement en arrière-plan ou service), dans le terminal pour un lancement au premier plan.
Une alerte « Données personnelles dans le contexte » inattendue¶
- Pour des données déjà retirées : elles sont encore dans l'historique envoyé. Une nouvelle conversation repart d'un historique propre.
- Qui revient après un redémarrage : normal, la mémoire des constats déjà signalés est perdue (et une session reprise renvoie son historique).
- Pour les adresses de votre entreprise : ajoutez le domaine à
PII_IGNORED_EMAIL_DOMAINSdans~/.tegvia/config.py, ou relevezPII_CONTACT_THRESHOLD, puis redémarrez le proxy. - Un fichier attendu n'a pas été signalé : le numéro doit satisfaire sa somme de contrôle, et les e-mails ou téléphones demandent au moins 10 valeurs distinctes dans un même bloc.
Session bloquée à cause du dossier de téléchargements¶
Chaque requête est refusée avec working directory is a downloads folder
ou session previously blocked: downloads folder. Claude Code a été lancé
dans un dossier de téléchargements. Quittez Claude
Code, déplacez uniquement les fichiers dont vous avez besoin vers un
dossier de projet dédié hors des dossiers de téléchargements (ne faites pas
confiance à un CLAUDE.md, ou à un fichier qu'il importe comme
AGENTS.md, trouvé dans un dossier de
téléchargements, ne le copiez pas) et relancez-le depuis là.
Un module semble inactif¶
Vérifiez qu'il n'est pas dans la liste des modules désactivés. canary_token est
désactivé par défaut.
Une mise à jour ne semble pas prise en compte¶
Le proxy en cours d'exécution garde l'ancienne version. Redémarrez Tegvia
(restart pour le service ; voir Mise à jour).
Obtenir plus de détails¶
TEGVIA_LOG_LEVEL n'est lue que dans l'environnement (pas dans
config.py). Avec le service en arrière-plan sous Linux, WSL ou macOS, une
variable définie dans votre terminal n'atteint pas le proxy : arrêtez le
service, lancez le lanceur autonome avec la
variable (TEGVIA_LOG_LEVEL=DEBUG sh launch/tegvia.sh), reproduisez le
problème, puis lisez la sortie du terminal. Sous Windows, définissez-la avec
setx TEGVIA_LOG_LEVEL DEBUG puis lancez restart du service ; le détail va
dans proxy.stderr.log, dans le dossier de données.
Journaux de session¶
- Les requêtes passent mais rien n'est journalisé : la base est
verrouillée par un autre programme, sur un disque en lecture seule ou
plein, ou son dossier n'est pas accessible en écriture. La journalisation
ne bloque jamais les requêtes : les entrées attendent dans
tegvia.db.pending(même dossier, jusqu'à 512 Mio) et le proxy réessaie seul toutes les 30 secondes. Aucun redémarrage n'est nécessaire. Libérez de la place, corrigez les droits ou fermez le programme qui utilise le fichier ; les entrées sont alors enregistrées, dans l'ordre et sans doublon, et le fichier disparaît. Des entrées ne sont perdues que si ce fichier ne peut pas être écrit non plus (disque plein ou en lecture seule, dossier inaccessible en écriture) ou s'il a atteint 512 Mio ; Claude Code affiche alors « WARN Tegvia : base de journaux indisponible et son fichier de secours est inaccessible : des entrées sont perdues. » Pendant sa relecture, le fichier est renommé (tegvia.db.pending.<n>peut apparaître brièvement) ; un reste terminant par.donepeut être supprimé. Messages possibles dansproxy.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 » (sans gravité, une entrée abîmée), « pending log file full or unwritable: dropped N item(s) » (la limite de 512 Mio est atteinte : des entrées sont perdues) et « log queue full: dropped N item(s) » (charge très forte). - Une ligne d'avertissement apparaît dans Claude Code, après « Protected by Tegvia » ou seule : « INFO Tegvia : base de journaux indisponible, N entrée(s) en attente de reconnexion. », ou « WARN Tegvia : base de journaux indisponible et son fichier de secours est inaccessible : des entrées sont perdues. » La base de journaux ne peut pas être écrite pour le moment ; voir l'entrée précédente. La ligne disparaît dès que la journalisation redevient normale. Tant que la base est indisponible, elle peut aussi apparaître seule, au début de n'importe quel texte de la réponse.
- La console affiche une carte d'avertissement sur la base de journaux : les textes sont « La base de journaux est indisponible : {n} entrée(s) en attente, à enregistrer dès qu'elle sera libérée. », « La base de journaux est indisponible pour le moment. Les nouvelles entrées sont mises en attente. » et « La base de journaux vient d'une version plus récente de Tegvia : {n} entrée(s) en attente. Mettez Tegvia à jour. » Mêmes causes et mêmes solutions que ci-dessus.
- La console est vide et affiche « Il manque une partie des données » :
la base a été mise à niveau par un Tegvia plus récent puis vous êtes
revenu à une version plus ancienne. Mettez de nouveau Tegvia à jour ; ne
supprimez pas la base sauf si vous acceptez de perdre l'historique. Les
nouvelles entrées restent entre-temps dans
tegvia.db.pending. - Le dossier de données se trouve sur un lecteur Windows partagé avec WSL
(
/mnt/c/...) : Tegvia évite alors le mode d'écriture différée, plus rapide mais peu fiable à cet endroit, et utilise le mode classique, plus lent. La journalisation fonctionne toujours. Faites tourner le proxy et la console du même côté (voir Windows et WSL ne voient pas les mêmes données) et placez si possible le dossier de données sur un chemin natif Linux ou Windows. - Fichiers
tegvia.db-walettegvia.db-shm: normaux tant que le proxy tourne. Ne les supprimez pas ; ne copiez ou ne déplacez la base que proxy arrêté. - Un fichier
tegvia.db.bak-v<n>est apparu : c'est la copie de sécurité faite avant une mise à niveau de la base (à la première requête journalisée après le démarrage du proxy). Supprimez-la quand tout fonctionne. Si la mise à niveau a échoué (erreur dansproxy.stderr.log), la copie contient vos données d'origine. Comme la base, elle contient des données sensibles. - Un fichier
tegvia.db.pendingest apparu : des entrées de journal attendent la base (voir plus haut). Il est supprimé une fois qu'elles sont enregistrées. Sous Linux et macOS il n'est lisible que par vous (sous Windows il prend les droits du dossier) et contient les mêmes données sensibles que la base. - La base ne cesse de grossir : rien n'est purgé. Arrêtez le proxy,
sauvegardez ou supprimez
tegvia.db.
Console web¶
- 403 « Forbidden » : la console n'accepte que les adresses
http://127.0.0.1:<port>/tegvia/ui/ethttp://localhost:<port>/tegvia/ui/(avec le bon port). Un autre nom d'hôte ou une autre adresse, par exemple le nom réseau de la machine, est refusé. - Page blanche : vérifiez que le proxy tourne (
tegvia-service status) et que vous utilisez le bon port, puis rechargez la page. La console nécessite JavaScript. Un message « Cette page n'a pas pu être chargée » avec un bouton « Réessayer » signifie que les données n'ont pas pu être lues : vérifiez le proxy, puis réessayez. - « Proxy injoignable » dans l'encart d'état : le proxy ne répond pas sur son port. La console est servie par le proxy : elle ne peut pas charger de données tant qu'il est arrêté. Démarrez Tegvia (service ou lanceur), puis rechargez la page. Le message peut aussi apparaître dans une page déjà ouverte.
- « Rien à afficher pour l'instant » : aucune requête n'est encore
passée par Tegvia, ou
TEGVIA_HOME,TEGVIA_LOG_DIRouTEGVIA_LOG_DBdésigne une autre base que celle du proxy (voir Windows et WSL ne voient pas les mêmes données). - « Il manque une partie des données » : la base vient d'une version plus récente de Tegvia, ou n'a pas pu être lue en entier. Les écrans concernés affichent « Il manque une partie des données : la base de journaux n’a pas pu être lue en entier, ou elle contient des entrées écrites par une version plus récente de Tegvia. Le reste est affiché ci-dessous. » Aucun nombre n'est donné. Si la base vient d'une version plus récente, mettez Tegvia à jour.
- La page Outils affiche « Aucun appel d’outil sur cette période » : aucun appel d'outil n'a été enregistré sur la période choisie. Juste après l'installation, les outils proposés à Claude Code sont déjà listés avec 0 appel, et les serveurs MCP apparaissent comme « jamais utilisés » tant qu'ils n'ont pas été appelés. Attendez un peu d'usage et vérifiez avec « Tout » avant de décider.
- Des outils déclarés ou des serveurs MCP manquent dans la page
Outils : les outils proposés au modèle sont lus dans les requêtes
enregistrées. Si ces données sont illisibles ou trop volumineuses, elles
sont ignorées et un avertissement est écrit dans
proxy.stderr.log. De même, au-delà de 4096 noms d'outils pour un même ensemble d'outils déclarés, les noms en trop sont ignorés avec un avertissement. Les appels sont toujours comptés ; seuls les chiffres « déclarés » et les serveurs « jamais utilisés » sont incomplets. - Les données ne bougent pas : la console ne se met pas à jour seule, cliquez sur « Actualiser ».
- « La documentation n'est pas construite » (page 404 après un clic sur
« Documentation » ou l'ouverture de
/tegvia/docs/) : cela n'arrive que dans une copie de développement, car l'archive distribuée livre la documentation déjà construite. Depuis la racine du dépôt, lancezuv pip install --python .venv -r requirements-docs.txtpuis.venv/bin/python scripts/build_console_docs.py(.venv\Scripts\python.exesous Windows), puis rechargez la page.
Réglages et protection¶
- « Base de données inutilisable au démarrage » (page Réglages en lecture
seule, ou
settings_defectdans/tegvia/status) : au démarrage, la base des journaux n'a pas pu être créée, ouverte ou lue, était verrouillée trop longtemps, ou vient d'une version plus récente de Tegvia. Le proxy applique alors les valeurs deconfig.pyet garde la protection active. Cherchez « settings store unusable » dansproxy.stderr.log(voir Fichiers utiles), vérifiez les droits sur le dossier de données et qu'aucun autre programme ne verrouilletegvia.db, ou mettez Tegvia à jour si la base est plus récente. Puis redémarrez Tegvia. Une base simplement absente n'est pas un défaut : elle est créée. - Le bandeau « Protection désactivée depuis le … » s'affiche : la
protection a été mise en pause depuis la console (par vous, ou par quelqu'un
ou un agent ayant accès à votre ordinateur : voyez l'événement « Réglage
modifié » dans les Alertes). Cliquez sur « Réactiver la protection », puis
ouvrez une nouvelle session Claude Code. En pause, un proxy démarré par le
service ou le lanceur retire la redirection de
settings.jsonet ne la remet pas : les sessions vont directement vers l'API. - Avertissement sur
settings.json(« settings.json n’a pas pu être restauré » ou « settings.json n’a pas pu être modifié ») : affiché quand le proxy a été lancé par le service, par le lanceur autonome ou à la main avec--configure. La protection a bien changé, mais le fichier de réglages de Claude Code est illisible, n'est pas du JSON valide ou n'est pas modifiable. Corrigez-le (le message donne la raison), puis redémarrez Tegvia. Tant quesettings.jsonpointe vers le proxy, Claude Code passe par lui, qui relaie sans inspecter si la protection est en pause. - La protection est réactivée mais rien n'est inspecté : seules les nouvelles sessions repassent par Tegvia. Ouvrez une nouvelle session ou redémarrez Claude Code.
- « Valeur refusée : … » à l'enregistrement : une valeur ne respecte pas les règles. Rien n'a été enregistré ; corrigez le champ indiqué.
- « Requête refusée : origine non reconnue. Rechargez la page. Rien n’a été enregistré. » : la console n'accepte les
écritures que depuis
http://127.0.0.1:<port>/tegvia/ui/ouhttp://localhost:<port>/tegvia/ui/. Rechargez la page à cette adresse. - « Le proxy ne répond pas. Rien n’a changé. » : démarrez Tegvia (voir Le proxy ne démarre pas), puis réessayez.
- Ma modification de
config.pyest sans effet : une valeur enregistrée depuis la console l'emporte surconfig.py. Utilisez « Rétablir » dans la page Réglages, puis enregistrez. - Un appel de l'agent est bloqué par
settings_tamper_check: l'agent a visé les routes de réglages ou la base de Tegvia. Faites le changement vous-même depuis la console.
Windows et WSL ne voient pas les mêmes données¶
Sous WSL, ~ est le dossier personnel Linux : ~/.tegvia n'est donc
pas le dossier .tegvia de votre profil Windows. Un proxy qui tourne sous
Windows et la console, tegvia-service status ou les journaux lus depuis WSL
regardent deux dossiers de données et deux bases différents : ils n'affichent
aucune donnée, ou un proxy qui « ne tourne pas », alors qu'il fonctionne. Pour
les mettre d'accord, faites tourner le proxy, la console web et les commandes
du service du même côté : tout dans WSL, ou tout sous Windows. Chaque côté a
son propre dossier de données et sa propre base, et ils ne sont pas faits pour
être partagés.
Ne faites pas pointer TEGVIA_HOME ou TEGVIA_LOG_DB vers le même dossier
ou fichier des deux côtés. Un
dossier de données situé sur un lecteur Windows (/mnt/c/...) ne doit pas
être partagé par des proxys des deux côtés, et il ne peut pas contenir de
config.py côté WSL : tous les fichiers y semblent modifiables par tout le
monde, le fichier est donc refusé.
Toutes les sessions Claude Code échouent après un plantage autonome¶
Si le lanceur autonome a été tué brutalement (kill -9, taskkill /F sans
/T), le proxy continue de tourner et Claude Code passe toujours par lui,
mais relancer est refusé avec le message « port 8736 is already in use ».
En cas de coupure de courant, le proxy a disparu et settings.json redirige
encore vers lui : toutes les sessions échouent alors à joindre l'API.
- Proxy encore en marche : trouvez son
<pid>aveclsof -nP -iTCP:8736 -sTCP:LISTEN(Linux, macOS) ounetstat -ano | findstr 8736(Windows, dernière colonne de la ligneLISTENING). Ignorez les autres lignes : ce sont des connexions clientes, dont celles de Claude Code, et les tuer ne libère pas le port. Sous Linux et macOS, arrêtez-le aveckill <pid>(un simple SIGTERM, qui retire aussi la redirection). Sous Windows, utilisez le Gestionnaire des tâches (Fin de tâche) outaskkill /F /PID <pid>; cet arrêt forcé ne retire pas la redirection, c'est le relancement qui le fait. Puis relancez (launch/tegvia.sh,tegvia.commandoutegvia.cmd). - Coupure de courant : relancez le lanceur ; il retire la redirection laissée
(
Tegvia: previous redirection left by an abrupt stop removed.) et démarre normalement. Arrêtez-le avec Ctrl-C pour laisser Claude Code sans redirection. - Ou réparez
settings.jsonà la main : voir Réparation après un arrêt brutal.
Si le lanceur refuse de démarrer, voir Refus.
L'installation a échoué ou l'icône n'est pas apparue¶
Ouvrez state/install.log dans le dossier de données
(~/.tegvia/state/install.log, ou %USERPROFILE%\.tegvia\state\install.log
sous Windows ; la ligne de résumé de install donne le chemin).
Il contient tout ce que install a affiché, par blocs, le plus récent à la
fin, et aucun secret. En cas d'échec des dépendances, consultez aussi
state/bootstrap.log.
Installation failed (see above).: la raison est affichée juste au-dessus de cette ligne et dansinstall.log.Tegvia installed, but the tray icon reported a problem (see above).: le service fonctionne ; lisez la ligneTray icon:au-dessus. Si elle indiqueautostart entry installed, but the icon could not be started now, l'icône apparaîtra à votre prochaine ouverture de session. Sur le port par défaut (8736), vous pouvez la lancer tout de suite aveclaunch\tegvia-tray.cmd(Windows) oush launch/tegvia-tray.sh(Linux). Sur un autre port installé, le lanceur manuel utiliserait 8736 : l'icône démarre à votre prochaine ouverture de session, ou relancezinstall.Tray icon started.: l'icône a été lancée immédiatement ; rien à faire.- L'icône a planté plus tard : une erreur inattendue est désormais écrite
dans
state/tray.logavant la sortie de l'icône. - La fenêtre s'est fermée avant que j'aie pu lire (Windows) :
install.cmdattend Entrée quand il est lancé dans une console ; sinon lisezinstall.log.
Service en arrière-plan¶
Commencez par sh launch/tegvia-service.sh status (launch\tegvia-service.cmd status
sous Windows) : il montre l'état, les chemins des journaux et la fin de
proxy.stderr.log. Voir Service en arrière-plan.
- systemd inutilisable (Linux, WSL) :
installn'écrit rien et explique pourquoi. Sous WSL, ajoutez[boot]/systemd=trueà/etc/wsl.conf, lancezwsl --shutdownet réessayez. Voir WSL. - Port occupé : un autre programme écoute sur le port du service (8736 par défaut, affiché
par
status). Trouvez-le (lsof -nP -iTCP:<port> -sTCP:LISTEN, ounetstat -ano | findstr <port>sous Windows), arrêtez-le, puis lancezstart; ou déplacez le service sur un port libre avecinstall --port N. Voir Port déjà utilisé. Le service retire d'abord toute redirection restante : les nouvelles sessions vont directement vers l'API. installrefuse un chemin : le chemin de Python ou du dossier Tegvia est relatif (ou, sous Windows, contient%ou"). Utilisez un chemin absolu.installrefuse :--portetTEGVIA_PORTdiffèrent (code de sortie 3) : le message nomme les deux valeurs. RetirezTEGVIA_PORTou donnez la même valeur à--port, puis relancezinstall.installrefuse un port invalide (code de sortie 2) :--portdoit être un nombre entier de 1024 à 65535. Corrigez-le puis relancezinstall.- « was not generated by Tegvia » : un fichier ou une tâche du même nom existe sans le marqueur de Tegvia. Tegvia refuse de l'écraser ; renommez-le ou supprimez-le vous-même.
statusdit que l'interpréteur ou le dossier n'existe plus : le dossier Tegvia ou Python a été déplacé ou supprimé. Relancezinstall.- Windows refuse un chemin (
%ou") : déplacez Tegvia ou utilisez un autre Python.TEGVIA_HOMErefusé : lancezsetx TEGVIA_HOME "<dossier>", ouvrez une nouvelle fenêtre (ou double-cliquez surinstall.cmd), puis lancezinstall.cmd. - Les sessions contournent Tegvia quelques secondes après une relance : normal, voir la fenêtre de relance.
Icône de la zone de notification¶
L'icône n'affiche jamais de boîte de dialogue d'erreur ; quand elle ne peut
pas fonctionner, elle affiche la raison et se termine avec le code 3.
Sous Linux et macOS, lancez-la à la main pour lire la raison
(sh launch/tegvia-tray.sh). Sous Windows, le lanceur démarre l'icône en
arrière-plan et n'affiche rien : la raison est dans
%USERPROFILE%\.tegvia\state\tray.log. Ce fichier (~/.tegvia/state/tray.log)
vaut partout ; launch/tegvia-service.sh status affiche une ligne Icon:. Voir
Icône de la zone de notification.
- Pas d'icône sous Linux, « No system tray found » : un bureau sans hôte
StatusNotifier, typiquement GNOME. Installez et activez l'extension
AppIndicator and KStatusNotifierItem Support, fermez et rouvrez votre
session, puis relancez
install(ou le lanceur manuel). - Pas d'icône, « No graphical session » : ni
DISPLAYniWAYLAND_DISPLAYn'est défini (SSH, connexion en console). Lancez-la depuis votre session de bureau. - Code de sortie 3 sous WSL : WSL n'a pas de zone de notification. Lancez
launch\tegvia-tray.cmdcôté Windows. - Code de sortie 3, « not supported » : système ou architecture non pris en charge (Linux x86_64, aarch64 et riscv64, macOS 11+, Windows 10/11 seulement).
- « the tray icon dependencies could not be installed » (Linux, macOS) :
vous êtes hors ligne, ou
requirements-tray.txtmanque dans votre copie de Tegvia (copie endommagée ou incomplète). Reconnectez-vous et relancez ; si le fichier manque, procurez-vous une copie complète (voir Installation depuis une archive). Le proxy n'est pas touché. - Windows : l'icône est absente : regardez derrière la flèche ^ et faites-la glisser sur la barre des tâches.
installa affiché « Tray icon: ... leaving it alone » : une entrée du même nom existe et Tegvia ne l'a pas créée. Elle n'est jamais écrasée : renommez-la ou supprimez-la vous-même, puis relancezinstall.- L'icône a disparu après que je l'ai quittée : elle n'est pas relancée automatiquement ; lancez-la à la main, ou rouvrez votre session. Quitter Tegvia a aussi arrêté Tegvia (quand le service est installé) : lancer l'icône le redémarre.
- L'icône affiche Erreur (« Tegvia : impossible de démarrer (code N) ») :
Tegvia n'a pas pu démarrer. Le code est le code de sortie de la commande de
démarrage (le plus souvent 1, pas toujours 78) et une notification unique
« L'action sur le service a échoué » l'affiche. Lisez
state/tray.logetproxy.stderr.logpour la cause (port déjà utilisé,settings.jsonouconfig.pyinvalide...), corrigez-la, puis choisissez Service > Démarrer dans le menu de l'icône ; l'icône redevient normale dès que Tegvia répond. Sous Windows, la tâche est relancée jusqu'à 3 fois, à une minute d'intervalle. Sous Linux et macOS, quand le système a accepté le démarrage mais que Tegvia échoue ensuite (par exemple port occupé), l'icône affiche Arrêté et non Erreur : consultez les mêmes journaux, puis utilisez Service > Démarrer. - « L'icône Tegvia est déjà lancée. » : une seule icône est autorisée ;
utilisez celle qui existe. Ce message ne s'affiche dans le terminal que sous
Linux et macOS ; sous Windows, un second lancement se termine sans rien
afficher et le message est écrit dans
tray.log. - L'icône indique Arrêté alors que Claude Code fonctionne : l'icône attend
deux vérifications ratées ; si le proxy tourne, vérifiez que l'icône et le
proxy utilisent le même port et le même dossier de données (
TEGVIA_PORT,TEGVIA_HOME). - Aucune notification de blocage : vérifiez Notifications dans le menu de l'icône, le mode Ne pas déranger de votre système, et que l'élément bloqué est bien un blocage (les avertissements sont désactivés par défaut).
- Notification macOS de « Script Editor » : normal.
- Pas d'entrée Service dans le menu : le service n'est pas installé sur cette machine, ou l'icône tourne sous Windows face à un proxy WSL.
- Je ne veux pas de l'icône :
install --no-trayinstalle le service sans l'icône, mais ne retire pas une entrée d'icône déjà existante, etuninstallretire tout le service, pas seulement l'icône. Pour garder le service sans l'icône, lancezuninstallpuisinstall --no-tray, ou retirez l'entrée de lancement automatique à la main et quittez l'icône (Quitter Tegvia dans son menu, qui arrête aussi le service : lancezstartensuite) :- Linux : supprimez
~/.config/autostart/io.tegvia.tray.desktop. - macOS : lancez
launchctl bootout gui/$(id -u)/io.tegvia.tray, puis supprimez~/Library/LaunchAgents/io.tegvia.tray.plist. - Windows : supprimez la valeur
TegviasousHKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run(par exemplereg delete HKCU\Software\Microsoft\Windows\CurrentVersion\Run /v Tegvia /f).
- Linux : supprimez