Troubleshooting¶

Dieser Guide behandelt häufige Probleme bei Entwicklung und Produktionsbetrieb von TCM365 sowie deren Lösungen.

Diagnostics Endpoints¶

TCM365 bietet eingebaute Diagnostics Endpoints für System Health Monitoring:

Diagnostics Endpoint verwenden¶

# Basis Health Check (keine Auth erforderlich)
curl http://localhost:8000/health

# Vollständige Diagnostics (erfordert JWT Token)
curl -H "Authorization: Bearer <token>" http://localhost:8000/api/v1/diagnostics

Beispiel-Antwort von /api/v1/diagnostics:

{
  "database": { "status": "ok", "latency": 2, "version": "15.4" },
  "redis": { "status": "unavailable", "fallback": "in-memory" },
  "storage": { "status": "ok", "backend": "local", "path": "./data" },
  "azureAd": { "status": "not_configured" }
}

Reparatur-Aktionen¶

# Fehlende Storage-Verzeichnisse erstellen
curl -X POST "http://localhost:8000/api/v1/diagnostics/repair?action=create_storage_dirs" \
  -H "Authorization: Bearer <token>"

# Ausstehende Datenbank-Migrationen ausführen
curl -X POST "http://localhost:8000/api/v1/diagnostics/repair?action=run_migrations" \
  -H "Authorization: Bearer <token>"

Structured Logging¶

Alle Backend Requests erzeugen strukturierte Log-Einträge:

2026-03-05T14:30:00Z | INFO | SnapshotsController [req=abc123 op=create user=admin] | Snapshot created

Log-Bestandteile¶

Request Tracing¶

Jeder Request erhält automatisch eine X-Request-ID:

• Wird automatisch generiert oder kann vom Client via X-Request-ID Header übergeben werden
• Erscheint in der Response als X-Request-ID Header
• Wird in allen zugehörigen Log-Einträgen mitgefuehrt
• Der X-Process-Time Response Header zeigt die Request-Dauer

Datenbank-Probleme¶

PostgreSQL Verbindung fehlgeschlagen¶

Symptome: Backend startet nicht mit Connection Refused oder Timeout Fehlern.

Lösungen:

1. Verifizieren, dass PostgreSQL läuft:

   # Docker
   docker compose -f infrastructure/docker/docker-compose.local.yml ps
   
   # System Service
   pg_isready -h localhost -p 5432
   

2. Umgebungsvariablen in backend-js/.env prüfen:

   DATABASE_HOST=localhost
   DATABASE_PORT=5432
   DATABASE_USERNAME=tcm_user
   DATABASE_PASSWORD=tcm_password
   DATABASE_NAME=tcm_db
   

3. Datenbank-Existenz verifizieren:

   psql -h localhost -U tcm_user -l | grep tcm_db
   

Migrations-Fehler¶

Symptome: npm run migration:run schlägt mit Fehlern fehl.

Lösungen:

1. Datenbankbenutzer hat ausreichende Berechtigungen:

   -- Der Migrations-Benutzer benötigt BYPASSRLS und CREATE Rechte
   ALTER ROLE tcm_user WITH BYPASSRLS;
   GRANT ALL PRIVILEGES ON DATABASE tcm_db TO tcm_user;
   

2. Für einen Neustart den Repair-Modus des Setup-Skripts verwenden:

   # Linux/macOS
   ./scripts/setup.sh    # Option 3: Repair wählen
   
   # Windows
   .\scripts\setup.ps1   # Option 3: Repair wählen
   

Row-Level Security funktioniert nicht¶

Symptome: RLS Policies filtern Daten nicht korrekt.

Lösungen:

1. Beide Datenbankrollen existieren verifizieren:

   SELECT rolname FROM pg_roles WHERE rolname IN ('tcm_admin', 'tcm_app');
   

2. tcm_admin hat BYPASSRLS verifizieren:

   SELECT rolname, rolbypassrls FROM pg_roles WHERE rolname = 'tcm_admin';
   

3. RLS Policies auf tenant-bezogenen Tabellen prüfen:

   SELECT tablename, policyname FROM pg_policies WHERE schemaname = 'public';
   

Authentifizierungsprobleme¶

Login gibt 401 zurück¶

Lösungen:

1. Admin-Benutzer existiert verifizieren:

   cd backend-js
   npm run db:seed
   

2. Credentials prüfen (Standard: admin@tcm.local / Admin123!TCM)

3. APP_SECRET_KEY ist gesetzt (min. 32 Zeichen):

   grep APP_SECRET_KEY backend-js/.env
   

JWT Token abgelaufen¶

Lösungen:

1. Token Refresh im Client implementieren:

   const response = await api.post('/auth/refresh');
   const newToken = response.data.access_token;
   

2. Token Lebensdauer erhöhen (nur Entwicklung):

   APP_ACCESS_TOKEN_EXPIRE_MINUTES=120
   

Azure AD SSO funktioniert nicht¶

Lösungen:

1. Alle Azure AD Umgebungsvariablen sind gesetzt verifizieren
2. Redirect URI stimmt exakt mit der Azure AD App Registration ueberein
3. App Registration hat die erforderlichen API Permissions mit Admin Consent

Redis Probleme¶

Redis Verbindung fehlgeschlagen¶

Auswirkung: Minimal. TCM365 fällt automatisch auf In-Memory Alternativen zurück.

Was auf Fallback umschaltet:

Lösungen:

1. Falls Redis benötigt wird, verifizieren dass es läuft:

   redis-cli ping
   # Erwartet: PONG
   

2. Redis URL prüfen:

   REDIS_URL="redis://localhost:6379/0"
   

3. Für lokale Entwicklung kann REDIS_URL komplett weggelassen werden.

Storage Probleme¶

Dateispeicher-Fehler¶

Symptome: Snapshot-Daten oder Reports können nicht gespeichert werden.

Lösungen:

1. Storage Backend Konfiguration prüfen:

   STORAGE_BACKEND=local
   LOCAL_STORAGE_PATH=./data
   

2. Storage-Verzeichnis existiert und ist beschreibbar:

   mkdir -p backend-js/data
   ls -la backend-js/data
   

3. Diagnostics Repair Endpoint verwenden:

   curl -X POST "http://localhost:8000/api/v1/diagnostics/repair?action=create_storage_dirs" \
     -H "Authorization: Bearer <token>"
   

Microsoft 365 / UTCM Probleme¶

UTCM Snapshot Job bleibt auf "notStarted"¶

Ursache: Der UTCM Service Principal ist nicht im Tenant registriert.

Lösung:

Connect-MgGraph -Scopes "Application.ReadWrite.All"
New-MgServicePrincipal -AppId '03b07b79-c5bc-4b5e-9bfa-13acf4a99998'

Teams/Exchange Snapshot gibt leere Daten zurück¶

Ursache: Dem UTCM Service Principal fehlt die erforderliche Directory Role.

Lösung: Die Global Reader Rolle dem UTCM SP zuweisen.

403 Forbidden bei Graph API Aufrufen¶

Ursache: Der App Registration fehlen die erforderlichen API Permissions.

Lösung:

1. Erforderliche Permissions in der M365 App Registration Anleitung prüfen
2. Fehlende Permissions in der Azure AD App Registration hinzufügen
3. Admin Consent für Application Permissions erteilen

Quota überschritten¶

Ursache: UTCM API Limits überschritten (10 Snapshot Jobs pro 24 Stunden).

Lösung: Auf Quota-Reset warten oder alte Snapshot Jobs löschen. TCM365 zeigt ein Quota-Banner im UI an.

Build und Kompilierungsprobleme¶

TypeScript Kompilierungsfehler¶

Lösungen:

1. Dependencies sind installiert sicherstellen:

   cd backend-js
   rm -rf node_modules
   npm ci
   

2. TypeScript Versionskompatibilitaet prüfen:

   npx tsc --version
   

3. Path Aliases loesen korrekt in tsconfig.json auf verifizieren

Vite Build schlägt fehl¶

Lösungen:

1. Vite Cache löschen:

   cd frontend
   rm -rf node_modules/.vite
   npm run build
   

2. Dependencies neu installieren:

   rm -rf node_modules
   npm ci
   

Performance-Probleme¶

Langsame API Antworten¶

Lösungen:

1. SQL Query Logging aktivieren um langsame Queries zu identifizieren:

   DATABASE_LOGGING=true
   

2. X-Process-Time Response Header für Request-Dauer prüfen

3. Datenbank-Indexes auf häufig abgefragten Spalten sicherstellen

4. Bei grossen Datensaetzen Pagination verifizieren

Häufige Fehlermeldungen¶