If you encountered a Kestrel error, you may want to ask for help in our OCA slack channel of Kestrel. A Kestrel veteran may guide you to further dig out the issue in Kestrel debug mode.

Kestrel Errors

Generally there are two categories of Kestrel errors:

  • Kestrel exceptions: the errors that have been thought by Kestrel developers and encapsulated in a Kestrel Exception class listed here: Kestrel Exceptions. These errors can be quickly explained by a Kestrel developer and their root causes are limited.

  • Generic Python exceptions: the errors that haven’t been captured by Kestrel runtime, which may be due to the incomplete try/catch coverage in Kestrel code or an error from a third party code, e.g., a dependent library or a Kestrel analytics (e.g., Python Analytics Interface). These errors usually need further debug, especially help from you to work with a Kestrel or third party code developer to debug.

Enable Debug Mode

You can run Kestrel in debug mode by either use the --debug flag of the Kestrel command-line utility, or create environment variable KESTREL_DEBUG with any value before launching Kestrel, which is useful when you use Kestrel in Jupyter Notebook. In the debug mode, all runtime data including caches and logs at debug level are at /tmp/kestrel-$USER/ ($TMPDIR/kestrel-$USER/ on macOS). The runtime logs of the latest created session is at /tmp/kestrel-$USER/session.log ($TMPDIR/kestrel-$USER/session.log on macOS).

Add Your Own Log Entry

If a Kestrel veteran assisted you in further debuging an issue, it is likely he/she will let you add a debug log entry to a specific Kestrel module/function to print out some value:

  1. Clone the kestrel-lang repo:

    $ git clone
  2. Ensure the following is in the module you’d like to debug (add if not):

    import logging
    _logger = logging.getLogger(__name__)
  3. Add debug log entry where you want:

  4. Install your local Kestrel build:

    $ pip install -e .
  5. Rerun Kestrel (command-line utility or restart Kestrel kernel in Jupyter) and check the entry you logged at /tmp/kestrel-$USER/session.log.