Häufige Fehler – gooddeploy

So sieht eine Fehlermeldung im Terminal aus: Meldung im Kasten, darunter der Hinweis, der Code und der Exit-Code:

╭─  FEHLER  ──────────────────────────────────────────╮
│ ✗ Recht "settings" für Projekt kunde-website fehlt. │
╰─────────────────────────────────────────────────────╯
  → Ein Admin kann dir das Recht "settings" auf kunde-website geben; gooddeploy whoami zeigt deine Rechte.
  Code SCOPE_MISSING · Exit 3

Ohne Terminal (Skript, CI, Pipe) steht dasselbe ohne Kasten:

✗ Recht "settings" für Projekt kunde-website fehlt.
  → Ein Admin kann dir das Recht "settings" auf kunde-website geben; gooddeploy whoami zeigt deine Rechte.
  Code SCOPE_MISSING · Exit 3

Mit --json steht der Code im Feld error.code. Den Exit-Code je Fehler findest du unter Für Skripte und CI.

Anmelden und Rechte

Code	Was ist los?	Was tun?
`UNAUTHENTICATED`	Du bist nicht angemeldet, oder der Zugangscode stimmt nicht (mehr); auch ein falsch abgetippter Code bei `login`. Mit mehreren Teams auch: Für das gewählte Team (`--team`, `GOODDEPLOY_TEAM` oder `.gooddeploy/project.json`) gibt es auf diesem Rechner keine Anmeldung.	`gooddeploy login` bzw. der genannte `gooddeploy login --team <name>`; `gooddeploy teams` zeigt deine Anmeldungen; in der CI `GOODDEPLOY_TOKEN` prüfen.
`SCOPE_MISSING`	Dir fehlt auf diesem Projekt ein Recht. Die Meldung nennt es.	`gooddeploy whoami` zeigt deine Rechte; goodDEV kann sie erweitern (Rechte).
`PLATFORM_UNAVAILABLE` bei `login --email`	Die Plattform bietet die Anmeldung per E-Mail noch nicht an („noch nicht verfügbar“).	Mit dem Zugangscode anmelden: `gooddeploy login` (fragt im Terminal von selbst danach) bzw. `gooddeploy login --token <code>`.
`PLATFORM_UNAVAILABLE` bei `env` oder `db`	Die Plattform bietet das noch nicht an („noch nicht verfügbar“, kommt später).	Variablen und Datenbank richtet bis dahin goodDEV ein; den Stand eines Deployments zeigen `gooddeploy status` und `gooddeploy inspect <id>`.
`NOT_FOUND`	Projekt oder Deployment gibt es nicht, oder es ist für deinen Zugangscode nicht freigegeben. Ohne Terminal auch: Das Projekt gibt es noch nicht, und gooddeploy legt es nicht nebenbei an.	Projektname bzw. ID prüfen (`gooddeploy ls`); ein neues Projekt mit `gooddeploy link <name>` anlegen (im Skript mit `--yes`).

Beim Deploy: Git und Upload

Code	Was ist los?	Was tun?
`GIT_DIRTY`	Es gibt nicht committete Änderungen, oder das Repo hat noch keinen Commit. gooddeploy lädt nur den letzten Commit hoch.	Änderungen committen oder verwerfen (`git status`). Bei `--dir`: Der Ordner muss im letzten Commit enthalten sein.
`NOT_GIT_REPO`	Du bist nicht in einem Git-Repo, oder `git` fehlt.	In den Repo-Ordner wechseln bzw. git installieren.
`GIT_SUBMODULES`	Das Repo nutzt Git-Submodule.	Werden nicht unterstützt; Inhalte direkt ins Repo übernehmen.
`GIT_LFS`	Dateien liegen in Git LFS.	Wird nicht unterstützt; Dateien normal einchecken.
`ARCHIVE_TOO_LARGE`	Der gepackte Commit ist zu groß (höchstens 100 MB komprimiert). Die Meldung nennt die größten Ordner und Dateien.	Was die Seite nicht braucht (Doku, Designs, Rohvideos), per `.gooddeployignore` vom Upload ausschließen, z. B. mit der Zeile `docs/`, und committen; siehe Große Dateien ausschließen. Oder mit `--dir` nur den nötigen Ordner deployen.
`ARCHIVE_REJECTED`	Das Archiv enthält unzulässige Pfade oder Symlinks.	Symlinks bzw. ungewöhnliche Pfade aus dem Repo entfernen.
`CONFIG_INVALID`	Die `gooddeploy.json` ist ungültig, z. B. eine Weiterleitung mit Schleife oder unerlaubten Zeichen. Die Meldung nennt die Stelle, etwa `redirects[2].destination`.	Die genannte Stelle korrigieren, committen und erneut deployen; siehe Weiterleitungen.
`TREE_MISMATCH`	Das hochgeladene Archiv passt nicht zum Commit.	Aus einem sauberen Stand erneut deployen. Nennt die Meldung Einträge mit `export-ignore` oder `export-subst` aus deiner `.gitattributes`, nimm sie dort heraus: Das Archiv lässt diese Dateien sonst weg oder ändert sie.

Beim Build

Code	Was ist los?	Was tun?
`BUILD_FAILED`	Der Build ist fehlgeschlagen.	Die Meldung nennt den Grund; lokal bauen und den Fehler beheben.
`STATIC_INDEX_MISSING`	Keine `index.html` gefunden.	`index.html` ins Repo-Root oder nach `public/` legen.
`BUILD_OUTPUT_MISSING`	Der Build hat keinen Ausgabeordner erzeugt, er ist leer oder ohne `index.html`.	Build-Skript und Ausgabeordner prüfen (Standard je Framework, z. B. `dist` bei Vite). Einen anderen Ausgabeordner gibst du mit `build.output` in der `gooddeploy.json` an (Projekteinstellungen kommen später).
`BUILDPACK_UNKNOWN`	Es gibt ein Build-Skript, aber kein bekanntes Framework.	Ein unterstütztes Framework nutzen oder lokal bauen, den Ausgabeordner (mit `index.html`) committen und nur ihn deployen, z. B. `gooddeploy deploy --dir dist`; `dist/` steht oft in der `.gitignore`, für `--dir` muss der Ordner aber committet sein (Eintrag dort entfernen). Eigene Einstellungen in einer `gooddeploy.json` (Framework, Ausgabeordner) kommen später.
`BUILDPACK_UNSUPPORTED`	Dieses Framework wird noch nicht unterstützt, z. B. Nuxt oder Remix mit Server-Rendering oder Bun; auch der Passwortschutz für Next.js meldet sich so.	Kommt später; siehe Was gebaut werden kann.
`BUILD_NOT_ALLOWED`	Für dieses Projekt sind nur fertige statische Dateien erlaubt.	Ohne `package.json` und Build deployen oder goodDEV fragen.
`BUILD_TIMEOUT`	Der Build dauerte länger als 15 Minuten.	Build verkürzen oder goodDEV fragen.
`CHECK_FAILED`	Die Seite wurde gebaut, antwortet aber nicht wie erwartet. Die Meldung zeigt, wenn vorhanden, die letzten Log-Zeilen der Seite (bis zu 50).	Log-Zeilen lesen, Startseite lokal prüfen und erneut deployen.

Live schalten und zurück

Code	Was ist los?	Was tun?
`DEPLOYMENT_NOT_READY`	Das Deployment ist nicht „bereit“ (läuft noch, ist fehlgeschlagen oder entfernt).	Mit `gooddeploy status` warten bzw. neu deployen.
`REQUIRED_CHECK_MISSING`	Ein Pflicht-Check fehlt für dieses Deployment; die Meldung nennt ihn. Pflicht sind immer `build`, `health` und `smoke`, dazu deine Checks aus `checks.required` in `gooddeploy.json`. Auch Deployments, die vor dem Update der Plattform gebaut wurden, haben die eingebauten Checks noch nicht.	Eigene Checks mit `gooddeploy checks report` melden (der Befehl steht in der Meldung); bei eingebauten Checks einmal neu deployen.
`REQUIRED_CHECK_FAILED`	Ein Pflicht-Check ist rot.	Fehler beheben und neu deployen oder den Check erneut melden.
`PROMOTE_IN_PROGRESS`	Gerade läuft schon ein Live-Schalten.	Kurz warten und erneut versuchen.
`VERIFY_FAILED_ROLLED_BACK`	Die neue Version war nach dem Umschalten nicht gesund; gooddeploy hat automatisch zurückgeschaltet.	Die vorherige Version ist wieder live. Fehler beheben und neu deployen.
`ROLLBACK_TARGET_UNAVAILABLE`	Es gibt keine frühere Live-Version, auf die du zurückschalten kannst.	`gooddeploy status` zeigt das Rollback-Ziel.

Aufräumen

Code	Was ist los?	Was tun?
`DEPLOYMENT_IS_PRODUCTION`	Die aktuelle Live-Version lässt sich nicht entfernen.	Erst `rollback` bzw. `promote`, oder das ganze Projekt mit `gooddeploy projects rm`.
`DEPLOYMENT_IN_PROGRESS`	Beim Entfernen eines Projekts läuft noch ein Build oder Start.	Warten, bis er fertig ist, dann erneut.
`VALIDATION_FAILED`	Eine Eingabe passt nicht, z. B. ein vertippter Befehl oder eine unbekannte Option, eine Live-Adresse bei `rm`, ein zu kurzes Passwort bei `protect` oder eine fehlende Bestätigung ohne Terminal.	Meldung lesen; sie nennt die passende Eingabe.

Verbindung und Plattform

Code	Was ist los?	Was tun?
`CLI_TOO_OLD`	Deine CLI ist zu alt für die Plattform.	`gooddeploy update` (Aktualisieren).
`PLATFORM_UNAVAILABLE`	Die Plattform ist nicht erreichbar, oder ein Warten hat zu lange gedauert. Beim Passwortschutz auch: gespeichert, aber noch nicht überall wirksam. Endet ein Deployment damit (z. B. „Start fehlgeschlagen“), lag eine Störung auf der Plattform vor, nicht bei dir.	Ist die Plattform nicht erreichbar: Internetverbindung prüfen und gleich noch einmal versuchen. Ein abgebrochener Vorgang läuft auf dem Server weiter: `gooddeploy status`. Bei einem gescheiterten Deployment: später noch einmal `gooddeploy deploy`; hält das an, goodDEV Bescheid geben.
`RATE_LIMITED`	Zu viele Anfragen in kurzer Zeit.	Kurz warten.
`CONCURRENT_MODIFICATION`	Jemand hat gleichzeitig dasselbe geändert.	Erneut versuchen.
`HOST_OWNED_BY_OTHER_PROJECT`	Eine Adresse gehört schon zu einem anderen Projekt.	goodDEV ansprechen.
`INTERNAL`, `INVALID_TRANSITION`, `SLOT_POOL_EXHAUSTED`, `AGENT_PROTOCOL_ERROR`, `ROLE_NOT_ALLOWED`	Fehler auf unserer Seite.	Bitte goodDEV melden, mit der `requestId` aus der Meldung. Steht keine dabei, starte den Befehl noch einmal mit `GOODDEPLOY_DEBUG=1` davor und schick die Ausgabe mit.

Noch nicht im Einsatz

Diese Codes sind festgelegt, kommen aber erst mit späteren Funktionen vor: BUILD_ENV_MISMATCH, BUILD_ENV_CHANGED (Build-Variablen), SECRET_IN_IMAGE (Prüfung auf Geheimnisse im Build) sowie LOGIN_CODE_INVALID, LOGIN_LINK_EXPIRED, LOGIN_LINK_USED (Anmeldung per Link und Code im Browser).