Flutter error tracking installation

Planned features

We currently don't support the following features:

Automatic exception capture
De-obfuscating stacktraces from obfuscated builds (--obfuscate and --split-debug-info)
Source code context associated with an exception
Flutter web support

These features will be added in future releases.

Install PostHog Flutter SDK

Required

SDK version requirement

A minimum SDK version of 5.7.0 is required, but we recommend keeping up to date with the latest version to ensure you have all of error tracking's features.

PostHog is available for install via Pub.

Configuration

Set your PostHog API key and change the automatic event tracking on if you wish the library to take care of it for you.

Remember that the application lifecycle events won't have any special context set for you by the time it is initialized. If you are using a self-hosted instance of PostHog you will need to have the public hostname or IP for your instance as well.

To start, add posthog_flutter to your pubspec.yaml:

pubspec.yaml

# rest of your code

dependencies:
  flutter:
    sdk: flutter
  posthog_flutter: ^5.0.0

# rest of your code

Then complete the set up for each platform:

For Session replay and Surveys you must setup the SDK manually by disabling the com.posthog.posthog.AUTO_INIT mode.

Android setup

There are 2 ways of initializing the SDK, automatically and manually.

Automatically:

Add your PostHog configuration to your AndroidManifest.xml file located in the android/app/src/main:

android/app/src/main/AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="your.package.name">
    <application>
        <!-- ... other configuration ... -->
        <meta-data android:name="com.posthog.posthog.API_KEY" android:value="<ph_project_api_key>" />
        <meta-data android:name="com.posthog.posthog.POSTHOG_HOST" android:value="https://us.i.posthog.com" />  <!-- usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com' -->
        <meta-data android:name="com.posthog.posthog.TRACK_APPLICATION_LIFECYCLE_EVENTS" android:value="true" />
        <meta-data android:name="com.posthog.posthog.DEBUG" android:value="true" />
    </application>
</manifest>

Or manually (more control and more configurations available):

Add your PostHog configuration to your AndroidManifest.xml file located in the android/app/src/main:

android/app/src/main/AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="your.package.name">
    <application>
        <!-- ... other configuration ... -->
        <meta-data android:name="com.posthog.posthog.AUTO_INIT" android:value="false" />
    </application>
</manifest>

In both cases, you'll also need to update the minimum Android SDK version to 21 in android/app/build.gradle:

android/app/build.gradle

// rest of your config

    defaultConfig {
        minSdkVersion 21
        // rest of your config
    }

// rest of your config

iOS setup

There are 2 ways of initializing the SDK, automatically and manually.

You'll need to have Cocoapods installed.

Automatically:

Add your PostHog configuration to the Info.plist file located in the ios/Runner directory:

ios/Runner/Info.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <!-- rest of your configuration -->
    <key>com.posthog.posthog.API_KEY</key>
    <string><ph_project_api_key></string>
    <key>com.posthog.posthog.POSTHOG_HOST</key>
    <string>https://us.i.posthog.com</string>
    <key>com.posthog.posthog.CAPTURE_APPLICATION_LIFECYCLE_EVENTS</key>
    <true/>
    <key>com.posthog.posthog.DEBUG</key>
    <true/>
</dict>
</plist>

Or manually (more control and more configurations available):

Add your PostHog configuration to the Info.plist file located in the ios/Runner directory:

ios/Runner/Info.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <!-- rest of your configuration -->
    <key>com.posthog.posthog.AUTO_INIT</key>
    <false/>
</dict>
</plist>

In both cases, you'll need to set the minimum platform version to iOS 13.0 in your Podfile:

ios/Podfile

platform :ios, '13.0'

# rest of your config

Dart setup (For manual step only)

If you followed the automatic SDK setup, then there's no more configuration needed in Dart.

If you followed the manual SDK setup:

Dart

import 'package:flutter/material.dart';

import 'package:posthog_flutter/posthog_flutter.dart';

Future<void> main() async {
  // init WidgetsFlutterBinding if not yet
  WidgetsFlutterBinding.ensureInitialized();
  final config = PostHogConfig('<ph_project_api_key>');
  config.debug = true;
  config.captureApplicationLifecycleEvents = true;
  // or EU Host: 'https://eu.i.posthog.com'
  config.host = 'https://us.i.posthog.com';
  await Posthog().setup(config);
  runApp(MyApp());
}

Web setup

For Web, add your Web snippet (which you can find in your project settings) in the <header> of your web/index.html file:

web/index.html

<!DOCTYPE html>
<html>

<head>
  <!-- ... other head elements ... -->

  <script async>
    !function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys getNextSurveyStep onSessionId".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
    posthog.init('<ph_project_api_key>', {
      api_host:'https://us.i.posthog.com', // 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'
      defaults: '2025-05-24',
    })
  </script>
</head>

<!-- other elements -->

</html>

For more information please check: /docs/libraries/js

Manually capture exceptions

Optional

Basic usage

You can manually capture exceptions using the captureException method:

Dart

try {
  // Your awesome code that may throw
  await someRiskyOperation();
} catch (exception, stackTrace) {
  // Capture the exception with PostHog
  await Posthog().captureException(
    error: exception,
    stackTrace: stackTrace,
    properties: {
      'user_action': 'button_press',
      'feature_name': 'data_sync',
    },
  );
}

This is helpful if you've built your own error handling logic or want to capture exceptions that are handled by your application code.

Error tracking configuration

You can configure error tracking behavior when setting up PostHog:

Dart

final config = PostHogConfig('<ph_project_api_key>');

// Configure error tracking
config.errorTrackingConfig.inAppIncludes = ['package:your_app'];
config.errorTrackingConfig.inAppExcludes = ['package:third_party_lib'];
config.errorTrackingConfig.inAppByDefault = true;

await Posthog().setup(config);

Configuration options:

inAppIncludes: List of package names to be considered inApp frames (takes precedence over excludes)
inAppExcludes: List of package names to be excluded from inApp frames
inAppByDefault: Whether frames are considered inApp by default when their origin cannot be determined

inApp frames are stack trace frames that belong to your application code (as opposed to third-party libraries or system code). These are highlighted in the PostHog error tracking interface to help you focus on the relevant parts of the stack trace.

Verify error tracking
Checkpoint
Confirm events are being sent to PostHog
Before proceeding, let's make sure exception events are being captured and sent to PostHog. You should see events appear in the activity feed.

Check for exceptions in PostHog

Flutter error tracking installation

Contents

Install PostHog Flutter SDK

Configuration

Android setup

iOS setup

Dart setup (For manual step only)

Web setup

Manually capture exceptions

Basic usage

Error tracking configuration

Verify error tracking

Community questions

Was this page useful?