Aller au contenu

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: ... : votre config.py contient une erreur à cette ligne. Corrigez-la, ou supprimez ou renommez le fichier.
  • tegvia: refusing to run .../config.py: not owned by the current user ou writable 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 dossier TEGVIA_HOME) ou rectifiez son propriétaire. Le proxy s'arrête avant de lire config.py et 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.log dans 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 outcome de 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.

  1. 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.
  2. tegvia-service status indique que le service n'est pas actif, ou que settings.json n'est pas redirigé → lancez start (service) ou démarrez le lanceur autonome, puis redémarrez Claude Code. Vérifiez qu'aucun ANTHROPIC_BASE_URL défini ailleurs (variable d'environnement du shell, réglages du projet .claude/settings.json) ne prend le dessus.
  3. 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.

  1. Lancez tegvia-service status, puis start (ou restart) si le service est arrêté. Consultez proxy.stderr.log dans le dossier de données : il indique pourquoi le proxy s'est arrêté (voir Le proxy ne démarre pas).
  2. Si vous ne voulez plus de Tegvia : lancez ./uninstall.sh (uninstall.cmd sous Windows), qui restaure settings.json.
  3. 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:LISTEN sous macOS, la ligne LISTENING de netstat -ano | findstr <port> sous Windows. Lancez ensuite tegvia-service status : si sa ligne Deployment: indique service, standalone ou manual, c'est Tegvia qui occupe le port ; si elle indique unknown, 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, utilisez TEGVIA_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

  1. Lisez la raison dans l'encadré « TEGVIA Protection ».
  2. 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_FINGERPRINTS dans ~/.tegvia/config.py et redémarrez le proxy. Les entrées invalides sont ignorées avec un avertissement indiquant leur nombre (une fois par nouvelle valeur invalide), dans proxy.stderr.log quand 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_DOMAINS dans ~/.tegvia/config.py, ou relevez PII_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 .done peut être supprimé. Messages possibles dans 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 » (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-wal et tegvia.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 dans proxy.stderr.log), la copie contient vos données d'origine. Comme la base, elle contient des données sensibles.
  • Un fichier tegvia.db.pending est 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/ et http://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_DIR ou TEGVIA_LOG_DB dé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, lancez uv pip install --python .venv -r requirements-docs.txt puis .venv/bin/python scripts/build_console_docs.py (.venv\Scripts\python.exe sous 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_defect dans /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 de config.py et garde la protection active. Cherchez « settings store unusable » dans proxy.stderr.log (voir Fichiers utiles), vérifiez les droits sur le dossier de données et qu'aucun autre programme ne verrouille tegvia.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.json et 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 que settings.json pointe 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/ ou http://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.py est sans effet : une valeur enregistrée depuis la console l'emporte sur config.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> avec lsof -nP -iTCP:8736 -sTCP:LISTEN (Linux, macOS) ou netstat -ano | findstr 8736 (Windows, dernière colonne de la ligne LISTENING). 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 avec kill <pid> (un simple SIGTERM, qui retire aussi la redirection). Sous Windows, utilisez le Gestionnaire des tâches (Fin de tâche) ou taskkill /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.command ou tegvia.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 dans install.log.
  • Tegvia installed, but the tray icon reported a problem (see above). : le service fonctionne ; lisez la ligne Tray icon: au-dessus. Si elle indique autostart 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 avec launch\tegvia-tray.cmd (Windows) ou sh 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 relancez install.
  • 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.log avant la sortie de l'icône.
  • La fenêtre s'est fermée avant que j'aie pu lire (Windows) : install.cmd attend Entrée quand il est lancé dans une console ; sinon lisez install.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) : install n'écrit rien et explique pourquoi. Sous WSL, ajoutez [boot] / systemd=true à /etc/wsl.conf, lancez wsl --shutdown et 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, ou netstat -ano | findstr <port> sous Windows), arrêtez-le, puis lancez start ; ou déplacez le service sur un port libre avec install --port N. Voir Port déjà utilisé. Le service retire d'abord toute redirection restante : les nouvelles sessions vont directement vers l'API.
  • install refuse un chemin : le chemin de Python ou du dossier Tegvia est relatif (ou, sous Windows, contient % ou "). Utilisez un chemin absolu.
  • install refuse : --port et TEGVIA_PORT diffèrent (code de sortie 3) : le message nomme les deux valeurs. Retirez TEGVIA_PORT ou donnez la même valeur à --port, puis relancez install.
  • install refuse un port invalide (code de sortie 2) : --port doit être un nombre entier de 1024 à 65535. Corrigez-le puis relancez install.
  • « 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.
  • status dit que l'interpréteur ou le dossier n'existe plus : le dossier Tegvia ou Python a été déplacé ou supprimé. Relancez install.
  • Windows refuse un chemin (% ou ") : déplacez Tegvia ou utilisez un autre Python. TEGVIA_HOME refusé : lancez setx TEGVIA_HOME "<dossier>", ouvrez une nouvelle fenêtre (ou double-cliquez sur install.cmd), puis lancez install.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 DISPLAY ni WAYLAND_DISPLAY n'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.cmd cô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.txt manque 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.
  • install a 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 relancez install.
  • 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.log et proxy.stderr.log pour la cause (port déjà utilisé, settings.json ou config.py invalide...), 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-tray installe le service sans l'icône, mais ne retire pas une entrée d'icône déjà existante, et uninstall retire tout le service, pas seulement l'icône. Pour garder le service sans l'icône, lancez uninstall puis install --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 : lancez start ensuite) :
    • 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 Tegvia sous HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run (par exemple reg delete HKCU\Software\Microsoft\Windows\CurrentVersion\Run /v Tegvia /f).