# Zammad nach System-Update: 500 Internal Server Error

## Zammad nach System-Update: 500 Internal Server Error

### Geltungsbereich

Zammad-**Paketinstallation** auf Debian/Ubuntu. Docker- und Source-Installationen haben andere Update- und Reparaturbefehle.

> **Getestetes Fehlerbild:** Nach einem unvollständigen System-/Paket-Update lieferte Zammad über den Reverse Proxy HTTP 500. In `production.log` fehlte `application.css`; teilweise waren die lokalen Zammad-Dienste auf `127.0.0.1:3000` beziehungsweise dem WebSocket-Port nicht erreichbar. Das Fertigstellen der Paketkonfiguration und ein erneuter Asset-Build behoben den Vorfall.
>
> **Nicht generell:** HTTP 500 nach einem Update hat nicht immer dieselbe Ursache. Asset-Build und Paket-Reparatur nur ausführen, wenn Paketstatus und Logs dazu passen.

### Symptome

- Browser: `500: An unknown error occurred`
- `/var/log/zammad/production.log`:

```text
The asset "application.css" is not present in the asset pipeline
```

- Reverse-Proxy-Log: `connect() failed (111: Connection refused)` zu einem lokalen Zammad-Port.

### 1. Ursache eingrenzen

Nicht zuerst den Reverse Proxy ändern. Zuerst Paketstatus, Dienste und lokale Anwendung prüfen:

```bash
sudo dpkg --audit
sudo systemctl status zammad zammad-web zammad-worker zammad-websocket --no-pager
sudo journalctl -u zammad -u zammad-web -u zammad-worker -u zammad-websocket -n 100 --no-pager
sudo tail -n 100 /var/log/zammad/production.log
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/
```

Interpretation:

- **Port nicht erreichbar:** zuerst Zammad-Dienste und Paketkonfiguration reparieren.
- **Lokaler Request liefert ebenfalls 500 und Asset-Fehler steht im Log:** Asset-/Postinstall-Schritt ist wahrscheinlich unvollständig.
- **Lokal erfolgreich, extern fehlerhaft:** erst dann Reverse Proxy, TLS und Upstream untersuchen.

### 2. Vor Änderungen sichern

Zammad empfiehlt vor Updates ein vollständiges Backup gemäss der offiziellen Backup-Dokumentation, ausserdem Release Notes lesen und keine Hauptversionen überspringen.

### 3. Unterbrochene Paketkonfiguration fertigstellen

Zammad stoppen, damit Datenbank- und Asset-Schritte nicht gegen laufende Dienste laufen:

```bash
sudo systemctl stop zammad
sudo apt update
sudo apt --fix-broken install
sudo dpkg --configure -a
```

`apt full-upgrade -y` ist **kein** pauschaler Reparaturschritt; es gehört in einen separat geprüften Wartungsplan.

### 4. Assets nur bei bestätigtem Asset-Fehler neu bauen

Aktuelle Zammad-Pakete führen ihre Migrations- und Precompile-Schritte normalerweise selbst aus. Der Paket-Precompile-Task bereitet auch die JavaScript-Umgebung vor und ruft anschliessend `assets:precompile` auf. Deshalb den übergeordneten Paket-Task verwenden:

```bash
sudo zammad run rake zammad:package:precompile
```

Nicht standardmässig direkt `rake assets:precompile` ausführen; der Paket-Task bildet die aktuelle Postinstall-Logik vollständiger ab.

Schlägt der Task fehl, die Fehlermeldung sichern und insbesondere Paketstatus, Node/pnpm-Umgebung und Datenbankerreichbarkeit prüfen.

### 5. Starten und validieren

```bash
sudo systemctl start zammad
sudo systemctl status zammad zammad-web zammad-worker zammad-websocket --no-pager
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/
sudo du -sh /opt/zammad/public/assets
sudo tail -n 100 /var/log/zammad/production.log
```

Erst danach den öffentlichen URL-Pfad testen und bei Bedarf Nginx-Config prüfen:

```bash
sudo nginx -t
sudo systemctl reload nginx
```

### Root Cause in diesem Vorfall

Das System-Update liess die Zammad-Paketkonfiguration unvollständig zurück; Rails und Datenbank liefen, aber die Frontend-Assets waren nicht korrekt gebaut. Der Reverse Proxy war nicht die Ursache.

### Prävention

Zammad empfiehlt für Paketinstallationen folgende Reihenfolge, insbesondere wenn Zammad und das Betriebssystem zusammen aktualisiert werden:

1. Abhängigkeiten prüfen.
2. Zammad stoppen.
3. Backup erstellen.
4. Zammad vorübergehend mit `apt-mark hold zammad` zurückhalten.
5. Betriebssystem-Pakete aktualisieren.
6. Zammad-Hold aufheben und Zammad aktualisieren.
7. Release Notes und gegebenenfalls Elasticsearch-Update prüfen.

Beispiel gemäss Herstellerablauf:

```bash
sudo systemctl stop zammad
sudo apt update
sudo apt-mark hold zammad
sudo apt upgrade
sudo apt-mark unhold zammad
sudo apt upgrade
```

### Lessons Learned

- Erst lokale App-Funktion (`127.0.0.1:3000`) prüfen, dann Reverse Proxy.
- Nach unvollständigen Updates: `dpkg --configure -a`, `apt --fix-broken install`, dann den Zammad-Paket-Precompile-Task.
- Ein fehlendes `application.css` deutet auf fehlgeschlagene Asset-Postinstall-Schritte hin, nicht auf ein Reverse-Proxy-Problem.

### Quellen

- [Zammad: Updating Zammad (Paketinstallation)](https://docs.zammad.org/en/latest/install-update.html)
- [Zammad: Paketinstallation und Dienste](https://docs.zammad.org/en/latest/install/package.html)
- [Zammad-Quellcode: Paket-Precompile-Task](https://github.com/zammad/zammad/blob/develop/lib/tasks/zammad/package/precompile.rb)

---

*Quelle: Obsidian `Knowledge Base/Troubleshooting/Zammad nach System Update 500 Internal Server Error.md` · Stand: 2026-10-12 · Automatisiert publiziert durch Hermes.*