Messages d'erreur et codes de sortie

Traduction automatique provisoire, non révisée. En cas de doute, consultez la version anglaise, qui fait foi.

Les messages d'échec de Kent forment un ensemble court et fixe. Chacun nomme la commande qui l'a produit, si bien qu'un message vous dit à la fois ce qui a mal tourné et où. Cette page les liste tous.

Kent s'exprime en anglais : les messages ci-dessous sont donc reproduits tels qu'ils apparaissent dans votre terminal, et seule l'explication de chacun est traduite.

Codes de sortie

Il n'y a pas de code distinct par type d'échec. Dans un script, testez le code de sortie pour décider si la commande a fonctionné, et lisez le message pour savoir pourquoi elle n'a pas fonctionné :

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

Erreurs de ligne de commande

Elles viennent de l'analyse de la ligne de commande, avant l'ouverture de toute base de données. Chacune est suivie du listage d'utilisation complet, le même texte qu'affiche kent help.

$ 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 et kent archive font exception : elles prennent des options plutôt qu'une base de données positionnelle, si bien qu'une base omise est signalée comme une option manquante.

$ 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 et restore exigent toutes deux --out, là où sqldump la traite comme facultative. Un zip ne peut pas être écrit sur la sortie standard et une base de données ne peut pas y être construite : ni l'une ni l'autre n'a donc de valeur par défaut sur laquelle se rabattre.

Erreurs de fichier et de base de données

Chaque message commence par kent et le nom de la commande.

Message	Ce que cela signifie
`kent createdb: NAME already exists`	Le fichier cible est déjà là. `createdb` n'écrase jamais ; supprimez le fichier vous-même si vous vouliez le remplacer.
`kent info: NAME does not exist`	Le chemin n'est pas là. Kent ne le crée délibérément pas. Le même message apparaît pour `details`.
`kent info: failed to open database: …`	Le fichier existe mais n'a pas pu être ouvert comme base de données Cordelia, le plus souvent parce qu'il n'en est pas une, ou parce que son schéma est plus ancien que ce que cette compilation accepte.
`kent info: failed to read schema version`	La base de données s'est ouverte, mais sa version de schéma n'a pas pu être lue.
`kent info: failed to list tables`	La base de données s'est ouverte, mais sa liste de tables n'a pas pu être lue.
`kent info: failed to count rows in NAME`	Le nombre de lignes d'une table précise n'a pas pu être lu. La table nommée est celle qui a échoué.
`kent createdb: failed to create database`	Le fichier n'a pas pu être créé, le plus souvent un répertoire manquant ou un problème de permissions sur le chemin cible.
`kent createdb: failed to create tables`	Le fichier a été créé mais le schéma n'a pas pu y être écrit.
`kent sqldump: NAME does not exist`	Le chemin donné à `--in` n'est pas là. Comme pour les autres commandes, Kent ne le crée pas.
`kent sqldump: refusing to write the export over its own source: NAME`	`--in` et `--out` désignent le même fichier. Refusé avant toute lecture, plutôt que de tronquer la base de données que vous demandiez d'exporter.
`kent files: NAME does not exist`	Le chemin n'est pas là, et Kent ne le crée pas. Voir `files`.
`kent archive: NAME does not exist`	Le chemin donné à `--in` n'est pas là. Comme pour toutes les autres commandes, Kent ne le crée pas.
`kent archive: cannot create the archive NAME`	La destination donnée à `--out` n'a pas pu être ouverte en écriture, le plus souvent un répertoire manquant ou un problème de permissions.
`kent archive: cannot write NAME`	Un fichier n'a pas pu être écrit dans le répertoire de préparation à côté de la destination. Souvent un disque plein : une archive a besoin de place pour elle-même et pour son contenu préparé en même temps. Voir `archive`.
`kent archive: cannot add NAME to the archive`	Un fichier préparé n'a pas pu être ajouté au zip.
`kent archive: finalising the archive failed`	Le zip n'a pas pu être fermé et achevé. L'archive partielle est supprimée plutôt que laissée en place.
`kent restore: NAME already exists`	La base de données que désigne `--out` est déjà là. `restore` n'en écrase jamais une, la même règle que suit `createdb`.
`kent restore: NAME is not readable as a kent archive: …`	Le fichier n'est pas un zip, ou n'a pas pu être ouvert. La raison sous-jacente suit les deux-points.
`kent restore: NAME is not a kent archive: it has no …`	C'est un zip, mais il lui manque le manifeste ou le schéma que porte toute archive.
`kent restore: this archive is format version N, but this build of kent understands version M at most`	L'archive a été écrite par un Kent plus récent. Kent refuse plutôt que de deviner un format qui lui est postérieur.
`kent restore: the archive's manifest lists table "NAME" but the archive has no …`	L'archive est incomplète. Refusée plutôt que restaurée en partie.
`kent restore: the archive's manifest claims N rows in "NAME" but it holds M`	L'archive est en désaccord avec elle-même : elle est endommagée ou a été mal construite.
`kent restore: the archive is inconsistent: its schema.sql stamps schema version N but its manifest says M`	Idem, pour la version de schéma.

Lorsqu'un message se termine par deux-points, l'erreur sous-jacente de la base de données le suit sur la même ligne. Ce détail final vient de la couche base de données de Cordelia : la même formulation apparaît donc dans Cordelia. Voir les messages d'erreur de Cordelia.

La base de données antérieure à cette compilation

Celle-ci mérite d'être signalée parce que la formulation peut se lire comme une corruption alors qu'il n'en est rien :

$ 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

Le fichier est intact. Il a simplement été écrit par une Cordelia plus ancienne que ce que cette compilation de Kent comprend, et il est refusé à l'ouverture plutôt que lu avec un schéma qui ne lui correspond pas.

kent sqldump et kent archive sont les deux commandes qui ne le refusent pas. Lire une ancienne base est exactement ce qu'on fait avant de la migrer : toutes deux la lisent donc quand même. sqldump le signale sur la sortie d'erreur ; c'est un avis, pas une erreur, et le code de sortie est 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 n'affiche aucune note de ce genre. Il consigne à la place la version de schéma trouvée dans le manifest.json de l'archive, si bien que l'information voyage avec l'archive plutôt que de défiler sur un terminal.

Kent n'a aucune commande qui migre une ancienne base sur place. La lire est l'entrée d'une migration, pas une migration en soi. Voir Exporter une base de données avec sqldump et Archiver une base de données avec archive.

Erreurs internes non gérées

Si quelque chose échappe à la gestion d'erreurs normale de Kent, c'est signalé sur la sortie d'erreur plutôt que sur la sortie standard, et le code de sortie reste 1 :

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

kent: unhandled exception of unknown type