Error Messages and Exit Codes

Kent's failure messages are a short, fixed set, listed here in full. Every one names the command that produced it, so a message tells you what went wrong and where.

Exit codes

There is no separate code per failure kind. In a script, test the exit code to decide whether the command worked, and read the message to find out why it didn't:

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

Command-line errors

These come from parsing the command line, before any database is opened. Each one is followed by the full usage listing, the same text kent help prints.

$ 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 and kent archive are the exceptions: they take flags rather than a positional database, so an omitted database is reported as a missing flag.

$ 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 and restore both require --out where sqldump treats it as optional. A zip cannot be written to standard output and a database cannot be built in one, so neither has a default to fall back on.

File and database errors

Each message begins with kent and the command name.

Message	What it means
`kent createdb: NAME already exists`	The target file is already there. `createdb` never overwrites; remove the file yourself if you meant to replace it.
`kent info: NAME does not exist`	The path isn't there. Kent deliberately does not create it. The same message appears for `details`.
`kent info: failed to open database: …`	The file exists but couldn't be opened as a Cordelia database, commonly because it isn't one, or because its schema is older than this build accepts.
`kent info: failed to read schema version`	The database opened, but its schema version couldn't be read.
`kent info: failed to list tables`	The database opened, but its table list couldn't be read.
`kent info: failed to count rows in NAME`	A specific table's row count couldn't be read. The table named is the one that failed.
`kent createdb: failed to create database`	The file couldn't be created, most often a missing directory or a permissions problem on the target path.
`kent createdb: failed to create tables`	The file was created but the schema couldn't be written into it.
`kent sqldump: NAME does not exist`	The path given to `--in` isn't there. As with the other commands, Kent does not create it.
`kent sqldump: refusing to write the export over its own source: NAME`	`--in` and `--out` name the same file. Refused before anything is read, rather than truncating the database you asked to export.
`kent files: NAME does not exist`	The path isn't there, and Kent does not create it. See `files`.
`kent archive: NAME does not exist`	The path given to `--in` isn't there. As with every other command, Kent does not create it.
`kent archive: cannot create the archive NAME`	The destination given to `--out` couldn't be opened for writing, most often a missing directory or a permissions problem.
`kent archive: cannot write NAME`	A file couldn't be written into the staging directory beside the destination. Commonly a full disk: an archive needs room for itself and its staged contents at once. See `archive`.
`kent archive: cannot add NAME to the archive`	A staged file couldn't be added to the zip.
`kent archive: finalising the archive failed`	The zip couldn't be closed and completed. The partial archive is removed rather than left behind.
`kent restore: NAME already exists`	The database `--out` names is already there. `restore` never overwrites one, the same rule `createdb` follows.
`kent restore: NAME is not readable as a kent archive: …`	The file isn't a zip, or couldn't be opened. The underlying reason follows the colon.
`kent restore: NAME is not a kent archive: it has no …`	It is a zip, but it lacks the manifest or the schema every archive carries.
`kent restore: this archive is format version N, but this build of kent understands version M at most`	The archive was written by a newer Kent. Kent refuses rather than guessing at a format that postdates it.
`kent restore: the archive's manifest lists table "NAME" but the archive has no …`	The archive is incomplete. Refused rather than restored in part.
`kent restore: the archive's manifest claims N rows in "NAME" but it holds M`	The archive disagrees with itself, so it is damaged or was built incorrectly.
`kent restore: the archive is inconsistent: its schema.sql stamps schema version N but its manifest says M`	The same, for the schema version.

Where a message ends in a colon, the underlying database error follows it on the same line. That trailing detail comes from Cordelia's database layer, so the same wording appears in Cordelia. See Cordelia's Error Messages.

The database that predates this build

This one is worth calling out because the wording can read like corruption when it isn't:

$ 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

The file is intact. It was simply written by an older Cordelia than this build of Kent understands, and it is refused at open time rather than read with a schema that doesn't match it.

kent sqldump and kent archive are the two commands that do not refuse it. Reading an old database out is exactly what you do before migrating it, so both read it anyway. sqldump says so on standard error; this is an advisory, not an error, and the exit code is 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 prints no such note. It records whatever schema version it found in the archive's own manifest.json instead, so the information travels with the archive rather than scrolling past on a terminal.

Kent has no command that migrates an old database in place. Reading one out is the input to a migration, not a migration in itself. See Exporting a Database with sqldump and Archiving a Database with archive.

Unhandled internal errors

If something escapes Kent's normal error handling, it is reported on standard error rather than standard output, and the exit code is still 1:

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

kent: unhandled exception of unknown type