Error reporting

Edit page

Record JavaScript errors from your app and investigate symbolicated stack traces in the EAS Observe dashboard.

Error reporting in EAS Observe is in preview and requires SDK 57 or later. Source maps for EAS Update, native crash reporting, and more are still to come.

The expo-observe library records JavaScript errors from your app alongside its performance metrics. Errors are persisted on-device, batched, and dispatched on the next flush. They appear in the Errors page of the EAS Observe dashboard.

Errors are captured through three paths: unhandled errors are recorded automatically, render errors are caught by ObserveErrorBoundary, and handled errors can be reported with Observe.reportError.

Unhandled errors

Unhandled JavaScript errors are recorded automatically. The library installs a global error handler when it is first imported, so no setup is required. React Native's own behavior is unchanged: the red box still appears in development, and fatal errors still terminate the app in production.

To turn off automatic recording, set errorHandlingEnabled to false via configure():

import { Observe } from 'expo-observe';

Observe.configure({
  errorHandlingEnabled: false,
});

This only affects unhandled errors. Errors caught by ObserveErrorBoundary or reported with Observe.reportError are still recorded.

Render errors

Without an error boundary, an error thrown while rendering is recorded by the global error handler as an unhandled error. Wrap a subtree with ObserveErrorBoundary to record it together with the React component stack and show a fallback UI in place of the subtree that threw:

import { ObserveErrorBoundary } from 'expo-observe';

export default function FeedScreen() {
  return (
    <ObserveErrorBoundary
      fallback={({ error, resetError }) => <ErrorScreen error={error} onRetry={resetError} />}>
      <Feed />
    </ObserveErrorBoundary>
  );
}

The fallback prop accepts a React element, null, or a function that receives the thrown error and a resetError callback. Calling resetError() clears the caught error and re-mounts the children, so they restart from a clean state.

To place a boundary around your whole app, pass errorBoundaryFallback to the ObserveRoot component instead of wrapping it manually:

src/app/_layout.tsx

import { ObserveRoot } from 'expo-observe';

export default function RootLayout() {
  return (
    <ObserveRoot errorBoundaryFallback={<FallbackScreen />}>
      <Stack />
    </ObserveRoot>
  );
}

Render errors that no boundary catches are still recorded by the global error handler.

Handled errors

Errors your code catches and recovers from reach neither the global handler nor an error boundary. Report them with Observe.reportError:

import { Observe } from 'expo-observe';

async function handleSync() {
  try {
    await syncCart();
  } catch (error) {
    Observe.reportError(error);
  }
}

reportError accepts any thrown value. An Error contributes its name, message, and stack trace. Any other value (a string, a plain object, a number) is stringified into the message without a stack trace.

Avoid Personally Identifiable Information (PII) in error messages. Everything you report is visible in the dashboard and is dispatched off-device.

Symbolicated stack traces

In a production app, your JavaScript is bundled and minified. Stack traces point at line and column positions in the generated bundle, not in your source files. A source map translates those positions back. When a source map is stored for a build, the dashboard shows the original file, line, and column for each frame, and links the build the error came from next to the stack trace.

If no source map is stored for the build, the dashboard shows the reported stack trace as-is. Frames then reference positions in the minified bundle, such as index.android.bundle:1:481231, and are difficult to map back to your code.

Upload source maps with EAS Build

To store a source map for each build, set uploadSourceMaps to true in the build profile in eas.json:

eas.json

{
  "build": {
    "production": {
      "uploadSourceMaps": true
    }
  }
}

With this setting, EAS Build uploads the source map produced when your app's JavaScript is bundled. Symbolication then works for every error reported from that build. No changes to your app code are required.

Note: Source map upload requires EAS CLI version 22.0.0 or later and only works for builds that run on EAS Build servers. Local builds created with eas build --local do not upload source maps.

The source code embedded in the source map (sourcesContent) is removed before upload. Only file names and position mappings are stored. If the upload fails, the build still completes and shows a warning in the build logs.

View errors

Open your project and navigate to Observe > Errors. The page lists the errors recorded in the selected time range. Click an error to see its stack trace and details.

Still to come

Error reporting is in preview, and the following are not available yet:

Source maps for EAS Update: errors from an app running an OTA update show the unsymbolicated stack trace.
Native crash reporting, including iOS symbolication, and more.

For native crash reporting today, use a service such as Sentry or BugSnag.