# Fehlerbehebung

Letzte Aktualisierung: 2026-03-06

## App reagiert nicht wie erwartet

### Symptom

UI zeigt alte Daten/Assets oder Verhalten wirkt stale.

### Lösung

```bash
docker compose restart php nginx
```

## Erstdiagnose mit Doctor

### Symptom

Unklar, ob das Problem aus ENV, DB, Storage, RBAC oder Scheduler kommt.

### Lösung

```bash
docker compose exec php sh -lc "php bin/doctor.php"
```

Bei `FAIL` zuerst diese Punkte beheben, danach erneut ausführen.

## Login/API verhalten sich unerwartet

### Symptom

401/403 bei API trotz gültigem Token.

### Checks

1. Für geschützte Endpunkte Authorization Header korrekt gesetzt (`Bearer <selector:secret>`)
2. Ausnahme: `/api/v1/auth/login` ist public und benötigt keinen Bearer-Header
3. Token nicht revoked/abgelaufen
4. Token hat erforderliche Permission
5. Bei tenant-scoped Token: Zugriff nur auf passende Tenant-Ressourcen

## Migration oder Schema-Probleme

### Symptom

Neue Felder/Features fehlen lokal.

### Lösung

1. Aktuelles Schema in `db/init/init.sql` prüfen
2. Für Bestandsumgebung idempotentes SQL-Update ausführen
3. Danach Container neu starten:

```bash
docker compose restart php
```

## i18n Fehler

### Symptom

Fehlende Translation-Keys oder Mixed-Language UI.

### Lösung

```bash
docker compose exec php vendor/bin/phpunit --bootstrap vendor/autoload.php tests/I18n/TranslationKeysTest.php
```

## PHPStan/Tests schlagen plötzlich fehl

### Symptom

Fehler nach Refactor, obwohl Seite lädt.

### Lösung

```bash
docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress
docker compose exec php vendor/bin/phpunit --bootstrap vendor/autoload.php
```

Dann gezielt betroffene Datei/Service prüfen.

## Swagger UI lädt ungestylt oder inkonsistent

### Symptom

API docs sehen nicht nach App-Theme aus.

### Lösung

1. Prüfen, dass `Buffer::set('style_groups', json_encode(['api-docs']))` gesetzt ist
2. Prüfen, dass `css/vendor-overrides/swagger-ui.css` über `config/assets.php` eingebunden ist
3. Hard-Reload im Browser