Errors

The SDK MUST provide the ability to be set as a hook to record uncaught exceptions. At the language level this is typically a global hook provided by the language itself. For framework integrations this MAY be part of middleware or another system.

This behavior is typically provided by a default integration that can be disabled.

The SDK MUST support identifying which stack frames are part of the user's application (as opposed to library or framework code). This SHOULD be done automatically where possible, and MUST be configurable by the user at startup, often declared as a package/module prefix.

The SDK SHOULD include lines of source code to provide context in stack traces. This is easier in interpreted languages, and MAY be hard or impossible in compiled ones.

The SDK SHOULD capture local variable names and values for each stack frame, where possible. Restrictions apply on some platforms — for example, it MAY only be possible to collect the values of parameters passed into each function, or it MAY be completely impossible.

This functionality MUST be gated behind the includeLocalVariables option, which MUST default to true.

The SDK SHOULD support turning compiled or obfuscated code/method names in stack traces back into the original names. Desymbolication always requires Sentry backend support. Not necessary for many languages.

This feature is RECOMMENDED for mobile and desktop SDKs.

If the application crashes shortly after SDK init, the SDK SHOULD provide a mechanism to guarantee transmission to Sentry. Ideally, SDKs could send the events in a separate process not impacted by the crashing application. With the limitations on mobile platforms, spawning an extra process only for sending envelopes is hard to achieve or impossible. The SDKs on these platforms send envelopes on a background thread to not block the UI thread or because they forbid network operations on the UI thread. A crash occurring shortly after the SDK init could lead to never reporting such crashes, keeping the users unaware of a critical bug.

When the app crashes, the SDK MUST check if it happens within two seconds after SDK init. If it does, the SDK MUST store that information on disk. The RECOMMENDED approach is using a marker file, which the SDK checks on initialization. If the SDK allows storing this information in another place to avoid creating an additional marker file and causing extra IO, the SDK MAY use such an approach.

If the platform allows it, the SDK MAY call flush directly after the detected start-up crash occurs and before the application terminates. If the SDK can guarantee transmission to Sentry while crashing, it MAY skip creating a marker file and making a blocking flush call on the next initialization.

If the marker file exists upon the next SDK initialization, the SDK MUST clear the marker and block the init execution up to five seconds in order to flush out pending envelopes. If the timeout of five seconds is exceeded, the SDK MUST release the init lock and continue flushing on a background thread.

While ideally the SDK SHOULD only flush out the crash event envelope, it is acceptable to call flush for all envelopes to reduce complexity, as most of the time there SHOULD NOT be too many envelopes in the offline cache.

This feature MUST NOT be user-configurable. The only reason to disable it should be if the feature is broken. The crash detection duration (two seconds) and flush duration (five seconds) MUST NOT be user-configurable.

Example Implementations

• Java
• Objective-C

The exception mechanism is an optional object on each exception describing how it was captured. It carries additional information about the capturing mechanism, including general exception values obtained from the operating system or runtime APIs.

Mechanism Attributes

Mechanism Type Naming

The type MUST help users and Sentry employees determine the responsible mechanism for capturing the exception. It MUST be reasonably unique to identify the integration or SDK API that performed the capture.

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

For SDK-invoked captures, the type MUST NOT be 'generic' and SHOULD follow the Trace Origin naming scheme whenever applicable. If a span wraps the exception capture logic, type SHOULD equal that span's sentry.origin attribute. If no specific span is present, the type SHOULD follow 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,
  }
  // ...
}

Synthetic Exceptions

Synthetic errors are errors that carry little meaning by themselves — they are often created at a central place (like a crash handler) and share the same title (Error, Segfault, etc.).

When synthetic is set, Sentry will try to use other information (top in-app frame function) rather than the exception type and value for the primary event display. Sentry will also ignore the exception type when grouping.

The synthetic flag SHOULD be set for all "segfaults" and similar low-information errors. Errors the SDK creates to add a stack trace to events that don't have one themselves SHOULD also be marked as synthetic (e.g. when attachStackTrace: true and the user captures a string message via captureException or captureMessage).

Exception groups allow representing a tree of related exceptions (e.g. Python ExceptionGroup, .NET AggregateException, JavaScript AggregateError). The tree is flattened into the values list with ID-based parent references.

The SDK SHOULD assign simple incrementing integers to each exception, starting with 0 for the root of the tree. When flattened into the values list, the last exception SHOULD have exception_id: 0, the previous one exception_id: 1, and so on.

The SDK SHOULD assign parent_id to all exceptions except the root exception (the last in the values list).

The source attribute SHOULD be populated with the name of the property or attribute of the parent exception that this exception was acquired from. For array properties, it SHOULD include the zero-based index.

Platform-specific examples:

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

Multiple exceptions in the values list represent a cause chain and MUST be sorted oldest to newest. For example, in Python:

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

Exception would appear first in the values list, followed by ValueError.

The exception attribute SHOULD be an object with a values attribute containing a list of one or more exception objects. Alternatively, the exception attribute MAY be a flat list of exception objects directly.