Beim Start eines Docker-Compose-Stacks – direkt per CLI oder über Portainer – bricht das Deployment manchmal mit dieser Fehlermeldung ab:
Failed to deploy a stack: service "docker" refers to undefined
volume mnt/docker: invalid compose projectDie Ursache ist fast immer dieselbe: Ein Service nutzt unter volumes: einen benannten Volume, der nicht im Top-Level-volumes:-Block deklariert ist. Docker Compose kennt den Namen dann nicht und bricht ab. Dieser Guide zeigt drei saubere Lösungen.
Ursache: benannter Volume vs. Bind-Mount
In Compose gibt es zwei Arten, Speicher einzubinden: Bind-Mounts (ein Host-Pfad, beginnt mit / oder ./) und benannte Volumes (ein Name ohne Pfad, z. B. dbdata). Ein benannter Volume muss zusätzlich im Top-Level-volumes:-Block stehen – sonst ist er „undefined“.
Lösung 1: Benannten Volume deklarieren
Fehlerhaft – der Volume dbdata wird genutzt, aber nie deklariert:
services:
db:
image: postgres:16
volumes:
- dbdata:/var/lib/postgresql/data # benannter Volume
# es fehlt der Top-Level volumes-Block!Korrekt – der Volume ist unten deklariert:
services:
db:
image: postgres:16
volumes:
- dbdata:/var/lib/postgresql/data
volumes:
dbdata:Lösung 2: Bind-Mount statt benanntem Volume
Willst du die Daten stattdessen in einem festen Host-Verzeichnis ablegen, nutze einen absoluten Pfad. Dann ist kein Top-Level-volumes:-Eintrag nötig:
services:
db:
image: postgres:16
volumes:
- /mnt/user/appdata/db:/var/lib/postgresql/dataGenau hier entsteht der Fehler oft: mnt/docker (ohne führenden /) wird als benannter Volume interpretiert statt als Pfad. Schreibe den Pfad absolut mit führendem Slash: /mnt/docker.
Lösung 3: In Portainer
In Portainer tritt der Fehler beim Deploy eines Stacks auf. Prüfe im Stack-Editor dieselben Punkte: entweder den benannten Volume im Top-Level-volumes:-Block ergänzen oder auf einen absoluten Bind-Mount-Pfad umstellen. Danach den Stack erneut deployen.
Prüfen & weiterführende Anleitungen
Nach der Korrektur validierst du die Datei mit docker compose config – das meldet undefinierte Volumes sofort. Grundlagen und weitere Stolperfallen findest du hier:
- Was ist Docker? Container einfach erklärt – inkl. Docker-Compose-Grundlagen
- Die 10 häufigsten Docker-Fehler – Ursachen und Lösungen
- Netbird mit Zitadel installieren (Docker Compose) – vollständiges Compose-Beispiel
Fazit
„Refers to undefined volume“ bedeutet fast immer: benannter Volume nicht deklariert oder ein Pfad ohne führenden Slash. Einmal den Top-Level-volumes:-Block ergänzt oder den Bind-Mount korrigiert – und der Stack startet.
