Skip to content

Troubleshooting

Jump to bottom
aiXis Studio edited this page Oct 4, 2026 · 1 revision

Troubleshooting / Dépannage

Before opening an issue / avant d'ouvrir une issue : export the diagnostics snapshot — GET http://127.0.0.1:8000/diagnostics?token=<TOKEN> or Settings → Export diagnostics. It contains no secrets.

🇬🇧 English

« macOS cannot verify this app » / app won't open

The build is unsigned — this is expected. Right-click Snitch.app → Open → confirm. Or: System Settings → Privacy & Security → Open Anyway.

Capture doesn't start / no packets appear

  • Live capture requires elevated privileges — run the backend from an admin/root terminal or approve the sudo prompt in the app.
  • Just testing? SNITCH_DEMO=1 python run_backend.py — synthetic traffic, no privileges needed.
  • Docker on macOS/Windows cannot see host traffic (VM) — use the native app.

UI asks for a token / « unauthorized »

The token is per-launch. Find it:

  • Electron: injected automatically — restart the app if stuck.
  • Docker/source: printed once in backend logs, or cat data/api_token.txt.
  • Open http://127.0.0.1:8000/?token=<TOKEN>.

« Read-only database » / logs can't be written

The data directory was probably created by a sudo run — its files are owned by root. Fix ownership:

# macOS
sudo chown -R "$USER" "$HOME/Library/Application Support/Snitch"
# Linux / source checkout
sudo chown -R "$USER" data/

Map shows no geolocation

  • First launch extracts the bundled DB-IP Lite — give it a few seconds.
  • For fresher data: drop GeoLite2-City.mmdb/GeoLite2-ASN.mmdb into <data_dir>/geo/, or use Settings → Download DB-IP Lite (explicit consent, the only outbound call).

Process attribution shows « unknown »

Expected for sockets that closed between the ~1.5 s psutil snapshots — attribution is best-effort. In Docker, only container processes are visible.

Port already in use (:8000)

Another process holds the port — lsof -i :8000 to find it, or set SNITCH_PORT=8001.

🇫🇷 Français

« macOS ne peut pas vérifier cette app »

La build n'est pas signée — c'est normal. Clic droit sur Snitch.app → Ouvrir → confirmer. Ou : Réglages Système → Confidentialité et sécurité → Ouvrir quand même.

La capture ne démarre pas / aucun paquet

  • La capture réelle exige des privilèges élevés — terminal admin/root, ou validez la demande sudo dans l'app.
  • Pour juste tester : SNITCH_DEMO=1 python run_backend.py — trafic synthétique, aucun privilège.
  • Docker sur macOS/Windows ne voit pas le trafic de l'hôte (VM) — utilisez l'app native.

L'UI demande un jeton / « unauthorized »

Le jeton change à chaque lancement. Où le trouver :

  • Electron : injecté automatiquement — redémarrez l'app si bloqué.
  • Docker/sources : affiché une fois dans les logs backend, ou cat data/api_token.txt.
  • Ouvrez http://127.0.0.1:8000/?token=<JETON>.

« Read-only database » / logs impossibles à écrire

Le dossier de données a probablement été créé par un lancement sudo — ses fichiers appartiennent à root. Corrigez le propriétaire :

# macOS
sudo chown -R "$USER" "$HOME/Library/Application Support/Snitch"
# Linux / checkout sources
sudo chown -R "$USER" data/

La carte n'affiche aucune géolocalisation

  • Le premier lancement extrait la DB-IP Lite embarquée — laissez quelques secondes.
  • Pour des données fraîches : déposez GeoLite2-City.mmdb/GeoLite2-ASN.mmdb dans <data_dir>/geo/, ou Réglages → Télécharger DB-IP Lite (consentement explicite, seul appel sortant).

Attribution processus « unknown »

Normal pour les sockets fermées entre deux instantanés psutil (~1,5 s) — attribution best-effort. Sous Docker, seuls les processus du conteneur sont visibles.

Port déjà utilisé (:8000)

Un autre processus occupe le port — lsof -i :8000, ou SNITCH_PORT=8001.

Snitch Wiki

Getting started / Démarrage

  • Installation — EN · FR
  • Usage / Utilisation — EN · FR

Docs (EN + FR)

Help / Aide (EN + FR)

Project / Projet

Clone this wiki locally