Fehlermeldungen und Exit-Codes

Vorläufige, ungeprüfte automatische Übersetzung. Im Zweifelsfall konsultieren Sie die englische Version, die als Referenzversion gilt.

Kents Fehlermeldungen sind ein kurzer, fester Satz. Jede von ihnen nennt den Befehl, der sie erzeugt hat, sodass eine Meldung Ihnen sowohl sagt, was schiefging, als auch wo. Diese Seite listet sie alle auf.

Kent gibt auf Englisch aus, die Meldungen unten stehen also genau so, wie sie in Ihrem Terminal erscheinen; übersetzt ist jeweils die Erklärung.

Exit-Codes

Es gibt keinen eigenen Code je Fehlerart. Prüfen Sie in einem Skript den Exit-Code, um zu entscheiden, ob der Befehl funktioniert hat, und lesen Sie die Meldung, um zu erfahren, warum nicht:

if ! kent info mydata.sqlite; then
    echo "could not report on the database" >&2
fi

Fehler auf der Kommandozeile

Diese stammen aus dem Auswerten der Kommandozeile, bevor überhaupt eine Datenbank geöffnet wird. Auf jeden folgt die vollständige Nutzungsübersicht, derselbe Text, den kent help ausgibt.

$ kent
missing command
usage: kent help
usage: kent createdb <dbfilename>
...

$ kent merge mydata.sqlite
unknown command: merge
usage: kent help
usage: kent createdb <dbfilename>
...

$ kent info
wrong number of arguments
usage: kent info <dbfilename>

kent sqldump und kent archive sind die Ausnahmen: sie nehmen Optionen statt einer positionierten Datenbank, eine ausgelassene Datenbank wird also als fehlende Option gemeldet.

$ kent sqldump
missing required flag: --in
usage: kent sqldump --in <dbfilename> [--out <outfile>] [--schema-only]

$ kent archive --in mydata.sqlite
missing required flag: --out
usage: kent archive --in <dbfilename> --out <archive>

archive und restore verlangen beide --out, wo sqldump es als optional behandelt. Ein Zip lässt sich nicht auf die Standardausgabe schreiben und eine Datenbank lässt sich nicht darin aufbauen, keiner von beiden hat also eine Rückfallebene.

Datei- und Datenbankfehler

Jede Meldung beginnt mit kent und dem Befehlsnamen.

Meldung	Was sie bedeutet
`kent createdb: NAME already exists`	Die Zieldatei ist schon da. `createdb` überschreibt nie; entfernen Sie die Datei selbst, wenn Sie sie ersetzen wollten.
`kent info: NAME does not exist`	Der Pfad ist nicht da. Kent legt ihn bewusst nicht an. Dieselbe Meldung erscheint für `details`.
`kent info: failed to open database: …`	Die Datei existiert, ließ sich aber nicht als Cordelia-Datenbank öffnen, meist, weil sie keine ist, oder weil ihr Schema älter ist, als dieser Build akzeptiert.
`kent info: failed to read schema version`	Die Datenbank ließ sich öffnen, aber ihre Schemaversion nicht lesen.
`kent info: failed to list tables`	Die Datenbank ließ sich öffnen, aber ihre Tabellenliste nicht lesen.
`kent info: failed to count rows in NAME`	Die Zeilenzahl einer bestimmten Tabelle ließ sich nicht lesen. Die genannte Tabelle ist die, bei der es fehlschlug.
`kent createdb: failed to create database`	Die Datei ließ sich nicht anlegen, meist ein fehlendes Verzeichnis oder ein Rechteproblem auf dem Zielpfad.
`kent createdb: failed to create tables`	Die Datei wurde angelegt, aber das Schema ließ sich nicht hineinschreiben.
`kent sqldump: NAME does not exist`	Der an `--in` übergebene Pfad ist nicht da. Wie bei den anderen Befehlen legt Kent ihn nicht an.
`kent sqldump: refusing to write the export over its own source: NAME`	`--in` und `--out` benennen dieselbe Datei. Abgelehnt, bevor irgendetwas gelesen wird, statt die Datenbank abzuschneiden, die Sie exportieren wollten.
`kent files: NAME does not exist`	Der Pfad ist nicht da, und Kent legt ihn nicht an. Siehe `files`.
`kent archive: NAME does not exist`	Der an `--in` übergebene Pfad ist nicht da. Wie bei jedem anderen Befehl legt Kent ihn nicht an.
`kent archive: cannot create the archive NAME`	Das an `--out` übergebene Ziel ließ sich nicht zum Schreiben öffnen, meist ein fehlendes Verzeichnis oder ein Rechteproblem.
`kent archive: cannot write NAME`	Eine Datei ließ sich nicht in das Zwischenverzeichnis neben dem Ziel schreiben. Oft eine volle Platte: ein Archiv braucht gleichzeitig Platz für sich und seinen Zwischenstand. Siehe `archive`.
`kent archive: cannot add NAME to the archive`	Eine zwischengespeicherte Datei ließ sich nicht in das Zip aufnehmen.
`kent archive: finalising the archive failed`	Das Zip ließ sich nicht schließen und fertigstellen. Das unvollständige Archiv wird entfernt statt liegen gelassen.
`kent restore: NAME already exists`	Die von `--out` benannte Datenbank ist schon da. `restore` überschreibt nie eine, dieselbe Regel, der `createdb` folgt.
`kent restore: NAME is not readable as a kent archive: …`	Die Datei ist kein Zip oder ließ sich nicht öffnen. Der zugrunde liegende Grund folgt nach dem Doppelpunkt.
`kent restore: NAME is not a kent archive: it has no …`	Es ist ein Zip, aber ihm fehlt das Manifest oder das Schema, das jedes Archiv trägt.
`kent restore: this archive is format version N, but this build of kent understands version M at most`	Das Archiv wurde von einem neueren Kent geschrieben. Kent lehnt ab, statt an einem Format herumzuraten, das jünger ist als es selbst.
`kent restore: the archive's manifest lists table "NAME" but the archive has no …`	Das Archiv ist unvollständig. Abgelehnt, statt teilweise wiederhergestellt zu werden.
`kent restore: the archive's manifest claims N rows in "NAME" but it holds M`	Das Archiv widerspricht sich selbst, ist also beschädigt oder wurde falsch erstellt.
`kent restore: the archive is inconsistent: its schema.sql stamps schema version N but its manifest says M`	Dasselbe, für die Schemaversion.

Wo eine Meldung mit einem Doppelpunkt endet, folgt der zugrunde liegende Datenbankfehler in derselben Zeile. Dieses angehängte Detail stammt aus Cordelias Datenbankschicht, dieselbe Formulierung erscheint also auch in Cordelia. Siehe Cordelias Fehlermeldungen.

Die Datenbank, die älter ist als dieser Build

Diese ist eigens hervorzuheben, weil die Formulierung nach Beschädigung klingen kann, obwohl es keine ist:

$ kent info old.sqlite
kent info: failed to open database: This database uses an older schema and cannot be opened; version 2 is required. Create a new database and import your .FIT files again.
$ echo $?
1

Die Datei ist unversehrt. Sie wurde nur von einer älteren Cordelia geschrieben, als dieser Kent-Build versteht, und wird beim Öffnen abgelehnt, statt mit einem Schema gelesen zu werden, das nicht zu ihr passt.

kent sqldump und kent archive sind die beiden Befehle, die sie nicht ablehnen. Eine alte Datenbank auszulesen ist genau das, was man vor einer Migration tut, also lesen beide sie trotzdem. sqldump sagt das auf der Standardfehlerausgabe; das ist ein Hinweis, kein Fehler, und der Exit-Code ist 0:

$ kent sqldump --in old.sqlite --out old.sql
kent sqldump: note: this database reports schema version 0, but this build of cordelia expects 2. Exporting it anyway.
$ echo $?
0

archive gibt keinen solchen Hinweis aus. Es hält die vorgefundene Schemaversion stattdessen in der manifest.json des Archivs fest, sodass die Information mit dem Archiv mitreist, statt auf einem Terminal vorbeizuscrollen.

Kent hat keinen Befehl, der eine alte Datenbank an Ort und Stelle migriert. Sie auszulesen ist die Eingabe für eine Migration, nicht selbst eine. Siehe Eine Datenbank mit sqldump exportieren und Eine Datenbank mit archive archivieren.

Unbehandelte interne Fehler

Entkommt etwas Kents normaler Fehlerbehandlung, wird es auf der Standardfehlerausgabe statt auf der Standardausgabe gemeldet, und der Exit-Code ist weiterhin 1:

$ kent info /some/unreadable/path.sqlite
kent: filesystem error: ...

kent: unhandled exception of unknown type