Decipher Python errors

When you develop Python queries in Deephaven, you eventually write code that causes an error. Deephaven's error output combines a Python traceback with Java stack traces from the query engine, so it can be long. This guide shows you how to read three kinds of errors so that you can quickly find and fix problems:

For a short checklist, see Tips for reading errors.

Parts of an error message

Errors in Python come in two kinds: syntax errors and exceptions. Let's start with a syntax error, which occurs when the Python interpreter encounters invalid syntax:

This produces some scary-looking output:

This output contains the clues you need to track down what is wrong with your program. In the IDE's Log panel, it has three parts:

  1. A log header that names the thread and the part of Deephaven that reported the error. Error running script means the error happened while the console ran your code.
  2. The Python error. For an exception raised while your code runs, this is a traceback. Each File line in the traceback is a frame that gives the file, line, and function of one call that led to the error. For a syntax error like this one, the File line gives the location of the invalid code instead. The last line gives the error type and message.
  3. A Java stack trace that lists the internal Java calls that led to the error. Each of its lines starts with at.

The IDE console shows the same error without the log header. The IDE's Log panel shows the time and the log level, such as ERROR, before the header. In Docker output or the terminal of a server you started with Gradle, each log line starts with the UTC date and time, and the log level follows the thread name.

The log shortens the thread and class names in the header to fit fixed-width columns:

  • The thread name keeps its last 20 characters. For example, r-Scheduler-Serial-1 is the end of DeephavenApiServer-Scheduler-Serial-1, the server thread that runs console commands.
  • The class name keeps its last 25 characters, after the log shortens package names to their initials. For example, .c.ConsoleServiceGrpcImpl is the end of i.d.s.c.ConsoleServiceGrpcImpl, the server class that handles console requests.

Note

Because the code ran as a console command, the file is <string>. Code you run from a notebook in the IDE also reports <string>. When the code comes from a file that Python loads itself, such as a module you import, the traceback shows that file's path instead.

In this case, the Python error shows that a SyntaxError occurred on line 1, the only line of our program. The caret (^) marks where Python stopped parsing the line.

The Java stack trace shows 24 lines of internal Java calls from Deephaven, jpy (the library that connects Python and Java in Deephaven), and the JDK. In most cases, you can ignore these internal details. As you work through a few errors, you learn to tell which parts of the output are your code and which parts are internal Deephaven code.

Exceptions in your own functions

Exceptions are unexpected events that occur during a program's execution. Now let's create our own exception. Here we create a function f(x) that raises an exception when x is 10 or 20.

Click to see the exception.

Here we see that the error is an Exception with the error message oops 1. The last line of the traceback gives the type and the message:

The two File lines above it are the frames, most recent call last:

In this case, the traceback is helpful. It shows that the error occurred when the program executed line 11 (f(10)) and then line 3 (raise Exception("oops 1")). in <module> marks top-level code in the command you ran, and in f marks code inside the function f. Calling f(1) did not cause an error. Only f(10) did.

Now that you have the hang of this, let's make the example a little more difficult. The function g below calls f from the previous example, so run that definition first.

Here you can see that line 5 in g (x += f(10)) triggered the exception in f:

Line numbers in a File "<string>" frame count from the start of the console command that defined the code. Here, line 9, in <module> and line 5, in g count from the start of the command that defined g, while line 3, in f counts from the start of the earlier command that defined f.

Exceptions in Deephaven tables

You can apply Python functions to Deephaven tables, and those functions can raise errors too. The first two examples in this section call the function f from Exceptions in your own functions, which raises an exception when its input is 10 or 20. Run that definition first.

Every example in this section calls Python from a query string: a string passed to a table operation to create a column or filter rows, such as "Y = f(X)" in the call to update.

Static tables

Here an error occurs when the query adds a new column to a static table. Because the table is static, Deephaven performs every calculation when your code calls update.

This error message is far more complex:
Without the internal Deephaven stack traces and the repeated copy of the first traceback at the end of the DHError message, the error is much shorter:

This is much easier to work with. Read it from the bottom up:

  • The final traceback shows that line 4 of the script, t1 = t.update("Y = f(X)"), called update, and that the call raised a DHError. Table operations in Deephaven's Python API raise a DHError when they fail.
  • The caused by section above it shows the original error: Exception: oops 1, raised on line 3 of function f.

Java marks the error that caused the one above it with a caused by or Caused by: line, so the original error is in the last one.

If you catch the DHError in your own code, its compact_traceback property gives a shorter version of this output.

The traceback contains two kinds of frames you didn't write:

  • _wrapper is a function that Deephaven generates to call f from the query engine. It also reports File "<string>", but it is not your code.
  • table.py is the file in the deephaven package that defines update. Its path and line numbers depend on your Deephaven version and installation.

As in the g example, line 3 in f counts from the start of the command that defined f, not of the command that called update.

Ticking tables

A ticking table is a table whose rows change while the query runs, such as a time table that adds a row every second. Errors in ticking tables are harder to trace than errors in static tables.

When you apply a method such as update to a ticking table, Deephaven first computes values for every row in the table, as it does for a static table. After that, it computes values only for added rows and for modified rows whose input columns changed. An error can therefore appear later, while the query runs.

This example calls f from Exceptions in your own functions, which raises an exception when its input is 10. The query runs for about 10 seconds before it fails, when X reaches 10.

Click to see the full stack trace.

Here the log header says Error in table update instead of Error running script: the error happened while Deephaven updated the table, not while the console ran your code. The thread differs too. aph-updateExecutor-9 is the end of PeriodicUpdateGraph-updateExecutor-9, a thread of the update graph, not the thread that runs console commands.

Unfortunately, the error doesn't name the query string or the line of your script that created the table. The traceback still names the function that raised the error, f, so search your code for query strings that call f.

The query string is missing because Deephaven vectorizes the call to f. It passes a whole chunk (block) of rows to the generated _wrapper function at once, and _wrapper calls f for each row. Errors from these calls don't include the query string. Deephaven usually vectorizes a formula that is only a direct call to a Python function, such as Y = f(X).

Other formulas run row by row in compiled code, and their errors start with In formula: followed by the query string. For example, an error in Y = f(X) + 1 starts with In formula: Y = f(X) + 1.

When a ticking table fails while it is open in the Deephaven IDE, its panel is covered by a warning icon and a message that begins with Unable to open table. The message gives an ID. To find the full error, search the Deephaven logs for that ID. For the f example, the log entry looks like this:

Not every ticking-table error hides the query string. In the next example, a query string on a ticking table calls Python's math.sqrt, which raises an error once its input is negative.

The table runs without error at first. After about 11 seconds, when X reaches -1, the table fails.

Click to see the exception.

Here, the ValueError under Caused by: shows that the query passed a negative value to math.sqrt.

Unlike the ticking f example above, this error names the query string that failed. Deephaven doesn't vectorize a call through a module, such as math.sqrt(X), so the formula runs row by row. The In formula: line shows the query string as written, Y = math.sqrt(X), so you can match it to your code.

Formula compilation errors

Now let's dig into an example with a more subtle problem. A query string can also fail before Deephaven computes any values. When it refers to a column or variable that doesn't exist, Deephaven can't compile the query string's formula. The engine throws a FormulaCompilationException, and the table operation raises it in Python as a DHError.

In this example, the same query string appears in two functions, but it is valid in only one of them.

This results in a long and complex error message:
Without the internal Deephaven stack traces and the repeated copy of the first traceback at the end of the DHError message, the error is much shorter:

Three lines of the short output locate the problem:

  • Exception message says that update could not find the variable X.
  • Full expression shows the expression that failed to compile, X * 3. That is the right side of the query string Y = X * 3, which appears twice in the code.
  • The last traceback shows that the failure occurred on line 9 of the console command, in f2.

Now that you know the location of the problem, you can see that the table that f2 creates has no X column, so its query string refers to a column that doesn't exist.

Tips for reading errors

Start by finding the error:

Then work through these steps to read the error:

  1. Skip the lines that start with at. They are internal Java calls.
  2. In the last Python traceback, find the line that gives the error type and message, such as Exception: oops 1 or deephaven.dherror.DHError: table update operation failed. : Cannot find variable or class X.
  3. Find the File "<string>" frames. These frames point to the code you ran in the console. Skip _wrapper and the frames in Deephaven's own files, such as table.py.
  4. Count each frame's line number from the first line of the console command that defined that code, not from the first line of your whole script.
  5. When a table operation fails, read the caused by and Caused by: sections. The last one in a chain holds the original error.
  6. Match the In formula: or Full expression text to the query string in your code.

Once you know which query and line failed, see Triage errors in queries for ways to isolate the cause.