Output, errors and exit codes

kater build, compile, run, test and sync print a line as each object starts and ends, then the end of the run and a summary, as dbt does, and write target/run_results.json. See kater build. Most other results are indented JSON, and --json makes them compact. Field and operation discovery print a readable list unless you add --json. An error prints as words that say what to do next. With --json it is JSON on stderr, with a code and a request id.

While a command works

A command prints its progress on stdout before its answer, one line for each event, with the time:

15:20:02  Find the account abc12345 ............................................ [OK]
15:20:03  Waiting for Kater to read the warehouse of snowflake_prod. 1s

With --json, stdout holds only the answer. These root options change the progress lines, as dbt’s do:

Waits

When a command waits for something it does not do itself, such as a job, a lock or the Kater API, it says what it waits for after one second, and again every ten seconds with the time so far. On a terminal it writes that line again in place. Every wait has a limit. At the limit the command stops and says what to do next. A call to the Kater API has 5 seconds to connect and a limit for its whole answer, and a Kater API that does not answer in time gives “The Kater API at URL did not answer in 15 s. Check that it runs, then try again.” The CLI uses the proxy and the certificates that HTTPS_PROXY and SSL_CERT_FILE name.

A command that reads a large project before its first object, such as kater build or kater ls, says so in the same way: Waiting for Kater to read the project. 1s. kater compile and kater run then say what they wait for until the first object ends, such as Waiting for Kater to compile 6 files. 1s: a first compile on an empty compile store reads each scope the selection reaches before any object ends.

Press Ctrl-C to stop waiting. A job keeps running, and the command says so: “Stopped waiting. The result (job 7f3a2c) keeps running. Run the same command again to read it.” The command exits with code 130. kater logs show --follow has no limit: Ctrl-C ends it.

Every event also goes to the log file at debug level: logs/kater.log at the content root, or ~/.kater/logs/kater.log outside one. The file moves aside at 10 MB and keeps four older files. Git ignores logs/, so kater git push never sends it.

Errors

An error prints as lines on stdout, as the progress lines do. The first says what Kater could not do. The next lines give the error’s words, what the warehouse said, and each diagnostic. Next: says what to do next. The last line gives the request id and where the log file is:

15:20:04  Error: Kater could not run revenue_by_month.
15:20:04    The warehouse refused the query.
15:20:04    Snowflake said: Object 'ORDERS' does not exist or not authorized.
15:20:04    Next: Check the SQL, then run kater debug to check the warehouse connection.
15:20:04    Request 4bf92f3577b34da6a3ce929d0e0e4736. Details are in logs/kater.log.

An unexpected error prints “Kater hit an unexpected error.” and a reference such as qerr_1472f2502160. Its record and its traceback go to the log file only. --quiet still prints every line of an error.

With --json, an error is one JSON line on stderr, and stdout is empty:

{"error": "No such command 'deploy'.", "code": "invalid_request", "request_id": "1d3b4350e7229b6bef6ca4f22aca9ceb"}

code says what kind of error it is. A program can act on these codes:

Other codes name an operation’s own failure, such as wait_limit for a wait that reached its limit. An error with not_signed_in, api_unreachable or api_timeout exits with code 2.

Exit codes

The exit codes are dbt’s.