Errors and exit codes¶
Exit codes¶
| Code | Meaning |
|---|---|
0 |
Success. This includes a dry run, a declined confirmation and a plan with nothing to do. |
1 |
An expected error: something the user can act on, such as a missing folder or a target that changed. The message is printed on standard error. |
2 |
Wrong usage: an unknown option, a missing argument or an invalid value. Typer prints the usage and the problem on standard error. |
Any other code, with a traceback, is a bug. Please report it.
Error messages¶
Without --json, an expected error is one line on standard error:
$ tunedex export m3u /tmp/out --playlist Nope
error: no playlist or folder at 'Nope'
With --json, standard output stays empty and standard error holds one JSON document:
{"error": {"code": "unknown_playlist", "message": "no playlist or folder at 'Nope'"}}
code is stable: a client can rely on it. message is for people and may change. Usage errors (exit code 2) stay plain text even with --json.
Error codes¶
| Code | When |
|---|---|
invalid_argument |
An argument has a valid form but cannot be used, such as a folder that does not exist or contradictory options. |
not_found |
A track, snapshot or file named in the command does not exist. |
needs_yes |
A command would ask for confirmation, but standard input is not a terminal. Pass --yes. |
unknown_playlist |
--playlist names no playlist or folder. The message suggests close names. |
stale_target |
A file the plan would write changed after the plan was made. Nothing was written; make the plan again. |
apply_failed |
Writing failed after it started. See below. |
not_a_library |
The database in the home is not a tunedex library. |
library_too_new |
The library was written by a newer tunedex. Upgrade tunedex. |
invalid_rule |
A rule, condition or fix in a rules file or in --where is invalid. The message says where. |
adapter_error |
A source or target file cannot be read or understood, such as a damaged Mixxx database. |
enrich_error |
enrich cannot run: fpcalc is missing, a service is unreachable, or a service gave a bad answer. |
plan_error |
Another planning or applying problem. |
snapshot_error |
A snapshot cannot be taken, read or restored. |
store_error |
Another problem with the library database. |
os_error |
The operating system refused an operation, such as a permission denied or a full disk. |
New codes can be added in any release. A client should handle an unknown code like a generic error.
apply_failed¶
The error document has three more fields:
{
"error": {
"code": "apply_failed",
"message": "applying failed ([Errno 28] No space left on device); the target was restored to its previous state",
"target": "m3u-568b52ce5ecb",
"snapshot": "000004-20261030T201502Z",
"restored": true
}
}
| Field | Meaning |
|---|---|
target |
The target that was being written. |
snapshot |
The snapshot taken before writing. |
restored |
true when tunedex put the target back as it was. false when it could not: restore it with tunedex snapshot restore <target> <snapshot> --apply. |