Error Handling Guide

TVM contains structured error classes to indicate specific types of error. Please raise a specific error type when possible, so that users can write code to handle a specific error category if necessary. You can directly raise the specific error object in python. In other languages like c++, you simply add <ErrorType>: prefix to the error message(see below).


Please refer to tvm.error for the list of errors.

Raise a Specific Error in C++

You can add <ErrorType>: prefix to your error message to raise an error of the corresponding type. Note that you do not have to add a new type tvm.error.TVMError will be raised by default when there is no error type prefix in the message. This mechanism works for both LOG(FATAL) and ICHECK macros. The following code gives an example on how to do so.

// src/
void ErrorTest(int x, int y) {
  ICHECK_EQ(x, y) << "ValueError: expect x and y to be equal."
  if (x == 1) {
    LOG(FATAL) << "InternalError: cannot reach here";

The above function is registered as PackedFunc into the python frontend, under the name tvm._api_internal._ErrorTest. Here is what will happen if we call the registered function:

>>> import tvm
>>> tvm.testing.ErrorTest(0, 1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/path/to/tvm/python/tvm/_ffi/_ctypes/", line 190, in __call__
    raise get_last_ffi_error()
ValueError: Traceback (most recent call last):
  [bt] (3) /path/to/tvm/build/ [0x7fab500b8ca8]
  [bt] (2) /path/to/tvm/build/ [0x7fab4f7f5126]
  [bt] (1) /path/to/tvm/build/ [0x7fab4f7eb2f8]
  [bt] (0) /path/to/tvm/build/ [0x7fab4f7a8d12]
  File "/path/to/tvm/src/api/", line 80
ValueError: Check failed: x == y (0 vs. 1) : expect x and y to be equal.
>>> tvm.testing.ErrorTest(1, 1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/path/to/tvm/python/tvm/_ffi/_ctypes/", line 190, in __call__
    raise get_last_ffi_error()
tvm.error.InternalError: Traceback (most recent call last):
  [bt] (3) /path/to/tvm/build/ [0x7fab500b8ca8]
  [bt] (2) /path/to/tvm/build/ [0x7fab4f7f5126]
  [bt] (1) /path/to/tvm/build/ [0x7fab4f7eb35c]
  [bt] (0) /path/to/tvm/build/ [0x7fab4f7a8d12]
  File "/path/to/tvm/src/api/", line 83
InternalError: cannot reach here
TVM hint: You hit an internal error. Please open a thread on to report it.

As you can see in the above example, TVM’s ffi system combines both the python and c++’s stacktrace into a single message, and generate the corresponding error class automatically.

How to choose an Error Type

You can go through the error types are listed below, try to use common sense and also refer to the choices in the existing code. We try to keep a reasonable amount of error types. If you feel there is a need to add a new error type, do the following steps:

  • Send a RFC proposal with a description and usage examples in the current codebase.

  • Add the new error type to tvm.error with clear documents.

  • Update the list in this file to include the new error type.

  • Change the code to use the new error type.

We also recommend to use less abstraction when creating the short error messages. The code is more readable in this way, and also opens path to craft specific error messages when necessary.

def preferred():
    # Very clear about what is being raised and what is the error message.
    raise OpNotImplemented("Operator relu is not implemented in the MXNet frontend")

def _op_not_implemented(op_name):
    return OpNotImplemented("Operator {} is not implemented.").format(op_name)

def not_preferred():
    # Introduces another level of indirection.
    raise _op_not_implemented("relu")

If we need to introduce a wrapper function that constructs multi-line error messages, please put wrapper in the same file so other developers can look up the implementation easily.