---
name: casaos-app-troubleshoot
description: CasaOS-App-Probleme diagnostizieren und beheben — Legacy, ausgegraut, Random-Namen, fehlende Icons, verwaiste Compose-Files.
version: 1.0.0
author: Hermes Agent (from Claude handover 2026-06-04)
license: MIT
metadata:
  hermes:
    tags: [casaos, zimaos, docker, troubleshooting, legacy, icons]
    related_skills: [zimaos-app-install, zimaos-administration, zimaos-quirks]
---

# CasaOS App Troubleshooting

Symptome und Fixes für häufige CasaOS-App-Probleme auf ZimaOS.

## Symptom: App erscheint als "Legacy"

**Ursache:** Container existiert (`docker ps` zeigt ihn) aber es gibt **kein Compose-File** unter `/var/lib/casaos/apps/<Name>/docker-compose.yml`. Der Container wurde vermutlich mit `docker run -d` gestartet.

**Erkennung:**
```bash
docker ps --filter "name=<name>" --format "{{.ID}} {{.Names}} {{.Image}} {{.Status}}"
# Prüfen ob Compose existiert:
ls /var/lib/casaos/apps/*/docker-compose.yml | xargs grep -l "<name>"
```

**Fix:**
1. Container-Config inspizieren: `docker inspect <container>`
2. Compose-File mit **identischer** Config schreiben (gleiche Image-Version, Ports, Volumes, Env, Network-Mode)
3. State-Daten: Wenn der Container Daten hat, Bind-Mount für das State-Verzeichnis setzen
4. Alten Container stoppen + entfernen: `docker stop <c> && docker rm <c>`
5. Neuen per Compose starten: `cd /var/lib/casaos/apps/<Name> && docker compose up -d`
6. ZimaOS-App-Management neustarten: `systemctl restart zimaos-app-management`

## Symptom: App erscheint "ausgegraut" / "uncontrolled"

**Ursache:** Compose-File existiert aber hat **keinen `x-casaos:` Block**. CasaOS erkennt ihn als "uncontrolled" — er läuft, aber ohne Metadaten.

**Erkennung:**
```bash
grep -L "x-casaos:" /var/lib/casaos/apps/*/docker-compose.yml
```

**Fix:**
`x-casaos:` Block ans Compose-File anhängen. Minimal:
```yaml
x-casaos:
  architectures: [amd64, arm64]
  title:
    custom: "Display Name"
  icon: "https://cdn.jsdelivr.net/gh/selfhst/icons/svg/<name>.svg"
  port_map: "<port>"
  index: /
  scheme: http
  store_app_id: <name>
```
Dann `systemctl restart zimaos-app-management`.

## Symptom: App hat Random-Namen (z.B. `noble_andres`, `breathtaking_maryann`)

**Ursache:** Compose-File hat kein `name:` Top-Level-Feld. Docker generiert dann `<adjektiv>_<vorname>` aus einer Wortliste.

**Erkennung:**
```bash
docker compose ls | grep -E '^[a-z]+_[a-z]+'
# Oder: Compose-Ordner hat Random-Namen
ls /var/lib/casaos/apps/
```

**Fix:**
1. `name: <appname>` ins Compose-File (Top-Level)
2. Ordner umbenennen: `mv /var/lib/casaos/apps/<random> /var/lib/casaos/apps/<AppName>`
3. Alten Container stoppen + entfernen
4. Container neu per Compose starten
5. `systemctl restart zimaos-app-management`

## Symptom: Icon fehlt oder zeigt 404

**Ursachen:**
- `icon:` URL zeigt auf einen lokalen App-Port (z.B. `http://192.168.178.171:3000/icon.svg`) der 404 liefert
- `icon:` ist leer
- `icon:` URL ist nicht erreichbar

**Fix:**
1. **Externe CDN-Icons:** `https://cdn.jsdelivr.net/gh/selfhst/icons/svg/<name>.svg`
2. **Base64 Data-URL (empfohlen für Self-Hosting):** SVG in base64 konvertieren und direkt einbetten:
   ```bash
   base64 -w0 /DATA/AppData/icons/<appname>.svg
   ```
   Dann: `icon: "data:image/svg+xml;base64,<base64-string>"`
3. Icon-Datei an einem persistenten Ort ablegen: `/DATA/AppData/icons/<appname>.svg`

**NICHT:** Icon-URL auf einen Port zeigen, den die App selbst bereitstellt — wenn der Container down ist, verschwindet das Icon.

## Symptom: Verwaiste Compose-Files (keine laufenden Container)

**Ursache:** Alte Experimente/Installationen, bei denen Container gestoppt/entfernt wurden aber die Compose-Files liegengeblieben sind.

**Erkennung:**
```bash
for app in /var/lib/casaos/apps/*/docker-compose.yml; do
  name=$(grep "container_name:" "$app" | awk '{print $2}')
  if ! docker ps -a --filter "name=$name" --format "{{.Names}}" | grep -q .; then
    echo "VERWAIST: $app (Container $name existiert nicht)"
  fi
done
```

**Fix:**
1. Prüfen ob die App wirklich nicht mehr gebraucht wird
2. Ordner löschen: `rm -rf /var/lib/casaos/apps/<name>/`
3. Auch die Daten unter `/DATA/AppData/<name>/` und `/var/lib/casaos/apps/<name>/` prüfen
4. Docker-Images evtl. bereinigen: `docker image prune`

## Schnell-Check: Alle Apps-Status

```bash
echo "=== Compose-Apps ===" && docker compose ls
echo ""
echo "=== Container ohne Compose (Legacy) ==="
docker ps --format "{{.Names}}" | while read c; do
  if ! grep -rl "container_name: $c" /var/lib/casaos/apps/*/docker-compose.yml >/dev/null 2>&1; then
    echo "LEGACY: $c"
  fi
done
echo ""
echo "=== Compose ohne x-casaos (ausgegraut) ==="
grep -L "x-casaos:" /var/lib/casaos/apps/*/docker-compose.yml 2>/dev/null
echo ""
echo "=== Compose ohne name: (Random-Namen) ==="
grep -L "^name:" /var/lib/casaos/apps/*/docker-compose.yml 2>/dev/null
```