Exception Interface

An exception consists of a list of values. In most cases, this list contains a single exception, with an optional stack trace interface. Multiple values represent a chained exception, and should be sent oldest to newest. That is, if your code does this:

try:
    raise Exception
except Exception as e:
    raise ValueError() from e

The order of exceptions would be Exception and then ValueError.

Attributes

type:

The type of exception, e.g. ValueError.

value:

The value of the exception (a string).

module:

The optional module, or package which the exception type lives in.

thread_id:

An optional value which refers to a thread in the Threads Interface.

mechanism:

An optional object describing the mechanism that created this exception (see below).

stacktrace:

An optional stack trace object corresponding to the Stack Trace Interface.

Exception Mechanism

The exception mechanism is an optional field residing in the Exception Interface. It carries additional information about the way the exception was created on the target system. This includes general exception values obtained from the operating system or runtime APIs, as well as mechanism-specific values.

Attributes

type:

Required unique identifier of this mechanism determining rendering and processing of the mechanism data.

description:

Optional human-readable description of the error mechanism and a possible hint on how to solve this error.

help_link:

Optional fully qualified URL to an online help resource, possible interpolated with error parameters.

handled:

Optional flag indicating whether the user has handled the exception (for example, via try ... catch).

meta:

Optional information from the operating system or runtime on the exception mechanism (see below).

data:

Arbitrary extra data that might help the user understand the error thrown by this mechanism.

Meta information

The mechanism metadata usually carries error codes reported by the runtime or operating system, along with a platform-dependent interpretation of these codes. SDKs can safely omit code names and descriptions for well-known error codes, as it will be filled out by Sentry. For proprietary or vendor-specific error codes, adding these values will give additional information to the user.

The meta key may contain one or more of the following attributes:

signal

Information on the POSIX signal. On Apple systems, signals also carry a code in addition to the signal number describing the signal in more detail. On Linux, this code does not exist.

number:

The POSIX signal number.

code:

Optional Apple signal code.

name:

Optional name of the signal based on the signal number.

code_name:

Optional name of the signal code.

mach_exception

A Mach Exception on Apple systems comprising a code triple and optional descriptions.

exception:

Required numeric exception number.

code:

Required numeric exception code.

subcode:

Required numeric exception subcode.

name:

Optional name of the exception constant in iOS / macOS.

errno

Error codes set by Linux system calls and some library functions as specified in ISO C99, POSIX.1-2001, and POSIX.1-2008. See errno(3) for more information.

number:

The error number

name:

Optional name of the error

Examples

The following examples illustrate payloads that may be sent by SDKs in various circumstances.

A single exception:

{
  "exception": {
    "type": "ValueError",
    "value": "My exception value",
    "module": "__builtins__",
    "stacktrace": {},
  }
}

A list of exceptions:

{
  "exception": {
    "values": [
      {
        "type": "Exception",
        "value": "Wrapped exception value",
        "module": "__builtins__"
      },
      {
        "type": "ValueError",
        "value": "Original Exception value",
        "module": "__builtins__"
      },
    ]
  }
}

iOS native mach exception with mechanism:

{
  "exception": {
    "type": "EXC_BAD_ACCESS",
    "value": "Attempted to dereference a null pointer",
    "meta": {
      "type": "mach",
      "handled": false,
      "data": {
        "relevant_address": "0x1"
      },
      "meta": {
        "signal": {
          "number": 10,
          "code": 0,
          "name": "SIGBUS",
          "code_name": "BUS_NOOP"
        },
        "mach_exception": {
          "code": 0,
          "subcode": 8,
          "exception": 1,
          "name": "EXC_BAD_ACCESS"
        }
      }
    }
  }
}

JavaScript unhandled promise rejection:

{
  "exception": {
    "type": "TypeError",
    "value": "Object [object Object] has no method 'foo'",
    "meta": {
      "type": "promise",
      "description": "This error originated either by throwing inside of an ...",
      "handled": false,
      "data": {
        "polyfill": "bluebird"
      }
    }
  }
}

Generic unhandled crash:

{
    "type": "generic",
    "handled": false
}