Exception Interface

The Exception Interface specifies an exception or error that occurred in a program.

An event may contain one or more exceptions in an attribute named exception.

The exception attribute should be an object with the attribute values containing a list of one or more values that are objects in the format described below. Alternatively, the exception attribute may be a flat list of objects in the format below.

Multiple values represent chained exceptions and should be sorted oldest to newest. For example, consider this Python code snippet:

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

Exception would be described first in the values list, followed by a description of 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 Thread Interface.

mechanism

An optional object describing the mechanism that

created this exception.

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 and captured ("capturing mechanism") on the target system. This includes general exception values obtained from the operating system or runtime APIs, as well as capturing mechanism-specific values.

Attributes

type

Required (string)

The identifier of the capturing mechanism that captured the exception. The chosen mechanism type MUST help users as well as Sentry employees determine the responsible mechanism for capturing the exception. This is either instrumentation within our SDKs or users manually capturing exceptions (for example via captureException).

The type MUST be reasonably unique so that identifying e.g. the integration or SDK API responsible for capturing is possible. There's no strict uniqueness requirement as in certain situations, multiple paths exist within one instrumentation, in which case it is fine to use a common mechanism type.

For user-invoked exception captures (e.g. via captureException), the type MUST be set to 'generic'.

For SDK-invoked exception captures, the mechanism type value MUST NOT be set to 'generic' and SHOULD follow the Trace Origin naming scheme whenever applicable. For example, if a span is wrapping the exception capture logic, type should be equal to this span's sentry.origin attribute. If no (specific) span is present, the type SHOULD be set to an adequate value, following the Trace Origin naming scheme as closely as possible.

startSpan(
  {
    name: 'Middleware',
    attributes: { 'sentry.origin': 'auto.http.express.middleware' },
  },
  () => {
    captureException(error, { 
      mechanism: { type: 'auto.http.express.middleware', handled: false } 
    });
  },
);

captureException(error, { 
  mechanism: { type: 'auto.browser.global_handlers.onerror', handled: false } 
});

function captureException(error, context) {
  const mechanism = {
    type: 'generic',
    handled: true,
    ...context?.mechanism,
  } 
  // ...
}

handled

Optional (boolean)

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

description

Optional (string)

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

help_link

Optional (string)

Fully qualified URL to an online help resource, possibly interpolated with error parameters.

synthetic

Optional (boolean)

Flag indicating that this error is synthetic. Synthetic errors are errors that carry little meaning by themselves. This may be because they are created at a central place (like a crash handler), and are all called the same: Error, Segfault etc. When the flag is set, Sentry will then try to use other information (top in-app frame function) rather than the exception type and value in the UI for the primary event display. Furthermore, if this flag is set, Sentry will ignore the exception type when grouping the exception into issues. This flag SHOULD be set for all "segfaults" for instance as every single error group would look very similar otherwise. Also, errors the SDK creates to add a stack trace to events that don't have one themselves SHOULD be marked as synthetic (This happens, for example, when users set attachStackTrace: true and capture a string message via captureException or captureMessage.)

exception_id

Optional (number)

An optional numeric value providing an ID for the exception relative to this specific event. The SDK SHOULD assign simple incrementing integers to each exception in the tree, starting with 0 for the root of the tree. In other words, when flattened into the list provided in the exception values on the event, the last exception in the list SHOULD have ID 0, the previous one SHOULD have ID 1, the next previous SHOULD have ID 2, etc.

parent_id

Optional (number)

An optional numeric value pointing at the exception_id that is the parent of this exception. The SDK SHOULD assign this to all exceptions except the root exception (the last to be listed in the exception values).

is_exception_group

Optional (boolean)

Flag indicating that this exception is part of an exception group type specific to the platform or language.

source

Optional (string)

An optional string value describing the source of the exception. The SDK SHOULD populate this with the name of the property or attribute of the parent exception that this exception was acquired from. In the case of an array, it SHOULD include the zero-based array index as well.

• Python Examples: "__context__", "__cause__", "exceptions[0]", "exceptions[1]"
• .NET Examples: "InnerException", "InnerExceptions[0]", "InnerExceptions[1]"
• JavaScript Examples: "cause", "errors[0]", "errors[1]"

meta

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

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.

ns_error

An NSError on Apple systems comprising of domain and code.

code

Required numeric error code.

domain

Required domain of the NSError as string.

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 multiple ways to send exceptions. Each example contains the exception part of the event payload and omits other attributes for simplicity.

A single exception:

{
  "exception": {
    "values": [
      {
        "type": "ValueError",
        "value": "my exception value",
        "module": "__builtins__",
        "stacktrace": {}
      }
    ]
  }
}

Chained exceptions:

{
  "exception": {
    "values": [
      {
        "type": "Exception",
        "value": "initial exception",
        "module": "__builtins__"
      },
      {
        "type": "ValueError",
        "value": "chained exception",
        "module": "__builtins__"
      }
    ]
  }
}

iOS native mach exception with mechanism:

{
  "exception": {
    "values": [
      {
        "type": "EXC_BAD_ACCESS",
        "value": "Attempted to dereference a null pointer",
        "mechanism": {
          "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": {
    "values": [
      {
        "type": "TypeError",
        "value": "Object [object Object] has no method 'foo'",
        "mechanism": {
          "type": "promise",
          "description": "This error originated either by throwing inside of an ...",
          "handled": false,
          "data": {
            "polyfill": "bluebird"
          }
        }
      }
    ]
  }
}

Generic unhandled crash:

{
  "exception": {
    "values": [
      {
        "type": "Error",
        "value": "An error occurred",
        "mechanism": {
          "type": "generic",
          "handled": false
        }
      }
    ]
  }
}

Flat list, omitting values:

{
  "exception": [
    {
      "type": "Error",
      "value": "An error occurred",
      "mechanism": {
        "type": "generic",
        "handled": false
      }
    }
  ]
}

Exception group:

{
  "exception": [
    {
      "type": "Error",
      "value": "An error occurred",
      "mechanism": {
        "type": "generic",
        "handled": true,
        "is_exception_group": true
        "exception_id": 0
      }
    },
    {
      "type": "Error",
      "value": "Another error occurred",
      "mechanism": {
        "type": "generic",
        "handled": false,
        "is_exception_group": true,
        "exception_id": 1,
        "parent_id": 0
      }
    }
  ]
}

`;