Error tracking installation

Error tracking enables you to track, investigate, and resolve exceptions your customers face. Getting this working requires installing PostHog:

Option 1: Add the JavaScript snippet to your HTML Recommended

This is the simplest way to get PostHog up and running. It only takes a few minutes.

Copy the snippet below and replace <ph_project_api_key> and <ph_client_api_host> with your project's values, then add it within the <head> tags at the base of your product - ideally just before the closing </head> tag. This ensures PostHog loads on any page users visit.

You can find the snippet pre-filled with this data in your project settings.

HTML

<script>
    !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.replace(".i.posthog.com","-assets.i.posthog.com")+"/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="init capture register register_once register_for_session unregister unregister_for_session getFeatureFlag getFeatureFlagPayload isFeatureEnabled reloadFeatureFlags updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures on onFeatureFlags onSessionId getSurveys getActiveMatchingSurveys renderSurvey canRenderSurvey getNextSurveyStep identify setPersonProperties group resetGroups setPersonPropertiesForFlags resetPersonPropertiesForFlags setGroupPropertiesForFlags resetGroupPropertiesForFlags reset get_distinct_id getGroups get_session_id get_session_replay_url alias set_config startSessionRecording stopSessionRecording sessionRecordingStarted captureException loadToolbar get_property getSessionProperty createPersonProfile opt_in_capturing opt_out_capturing has_opted_in_capturing has_opted_out_capturing clear_opt_in_out_capturing debug".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'})
</script>

Once the snippet is added, PostHog automatically captures $pageview and other events like button clicks. You can then enable other products, such as session replays, within your project settings.

Grouping products in one project (recommended)

If you have multiple customer-facing products (e.g. a marketing website + iOS app + web app), it's best to install PostHog on them all and group them in one project.

This makes it possible to track users across their entire journey (e.g. from visiting your marketing website to signing up for your product), or how they use your product across multiple platforms.

Set up a reverse proxy (recommended)

We recommend setting up a reverse proxy, so that events are less likely to be intercepted by tracking blockers.

We have our own managed reverse proxy service included in the Teams plan, which routes through our infrastructure and makes setting up your proxy easy.

If you don't want to use our managed service then there are several other options for creating a reverse proxy, including using Cloudflare, AWS Cloudfront, and Vercel.

Include ES5 support (optional)

If you need ES5 support for example to track Internet Explorer 11 replace /static/array.js in the snippet with /static/array.full.es5.js

Working with AI code editors?

If you’re working with AI code editors (like Loveable, Bolt.new, Replit, and others), it’s easy to install PostHog. All you have to do is ask (seriously). Specifically: in your tool, type a prompt like this: “I’d like to use PostHog to track events here; here is my install snippet.” Paste in your snippet. The tool will do the rest.

As of this time, some web-based AI builders (such as artifacts by Claude) don’t support access to external JS libraries. You’ll be able to ask it to use a placeholder, and then update it manually when you deploy to production.

Option 2: Install via package manager

yarn add posthog-js

And then include it with your project API key and host (which you can find in your project settings):

Web

import posthog from 'posthog-js'
posthog.init('<ph_project_api_key>', { api_host: 'https://us.i.posthog.com' })

See our framework specific docs for Next.js, React, Vue, Angular, Astro, Remix, and Svelte for more installation details.

Bundle all required extensions (advanced)

By default, the JavaScript Web library only loads the core functionality. It lazy-loads extensions such as surveys or the session replay 'recorder' when needed.

This can cause issues if:

You have a Content Security Policy (CSP) that blocks inline scripts.
You want to optimize your bundle at build time to ensure all dependencies are ready immediately.
Your app is running in environments like the Chrome Extension store or Electron that reject or block remote code loading.

To solve these issues, we have multiple import options available below.

Note: With any of the no-external options, the toolbar will be unavailable as this is only possible as a runtime dependency loaded directly from us.posthog.com.

Web

// No external code loading possible (this disables all extensions such as Replay, Surveys, Exceptions etc.)
import posthog from 'posthog-js/dist/module.no-external'

// No external code loading possible but all external dependencies pre-bundled
import posthog from 'posthog-js/dist/module.full.no-external'

// All external dependencies pre-bundled and with the ability to load external scripts (primarily useful is you use Site Apps)
import posthog from 'posthog-js/dist/module.full'

// Finally you can also import specific extra dependencies 
import "posthog-js/dist/recorder"
import "posthog-js/dist/surveys"
import "posthog-js/dist/exception-autocapture"
import "posthog-js/dist/tracing-headers"
import "posthog-js/dist/web-vitals"
import posthog from 'posthog-js/dist/module.no-external'

// All other posthog commands are the same as usual
posthog.init('<ph_project_api_key>', { api_host: 'https://us.i.posthog.com' })

Note: You should ensure if using this option that you always import posthog-js from the same module, otherwise multiple bundles could get included. At this time posthog-js/react does not work with any module import other than the default.

Don't want to send test data while developing?

If you don't want to send test data while you're developing, you can do the following:

Web

if (!window.location.host.includes('127.0.0.1') && !window.location.host.includes('localhost')) {
    posthog.init('<ph_project_api_key>', { api_host: 'https://us.i.posthog.com' })
}

Setting up exception autocapture

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

You can enable exception autocapture for the JavaScript Web SDK in the Error tracking section of your project settings.

When enabled, this automatically captures $exception events when errors are thrown by wrapping the window.onerror and window.onunhandledrejection listeners.

Manual error capture

It is also possible to manually capture exceptions using the captureException method:

JavaScript

posthog.captureException(error, additionalProperties)

Uploading source maps

If your source maps are not publicly hosted, you will need to upload them during your build process to see unminified code in your stack traces.

The posthog-cli handles this process. You will need to install it and upgrade to the latest version:

Terminal

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/PostHog/posthog/releases/download/posthog-cli-v0.0.4/posthog-cli-installer.sh | sh
posthog-cli-update

Authenticating the CLI

To authenticate the CLI you can call the login command and follow the instructions:

Terminal

posthog-cli login

If you are using the CLI in a CI/CD environment such as GitHub Actions you can set environment variables to authenticate. POSTHOG_CLI_ENV_ID and POSTHOG_CLI_TOKEN should be the number in your PostHog homepage URL and a personal API key respectively.

Uploading source maps

Once you've built your application and have bundled assets that serve your site, inject the context required by PostHog to associate the maps with the served code. You will then need to upload the modified assets to PostHog, and ensure that the modified asset bundles are the ones you're serving - if you serve a copy of the bundled assets as they were prior to running posthog-cli sourcemap inject, we won't be able to use the uploaded sourcemap to deminify or demangle your stack traces.

Both of these operations can be done by running the respective sourcemap commands:

Terminal

# Do the following prior to asset upload or publishing:
posthog-cli sourcemap inject --directory ./path/to/assets
posthog-cli sourcemap upload --directory ./path/to/assets
# Now publish the modified assets however you normally do so

Option 1: Add the JavaScript snippet to your HTML Recommended

Option 2: Install via package manager

Setting up exception autocapture

Manual error capture

Uploading source maps

Authenticating the CLI

Uploading source maps

Questions? Ask Max AI.

Community questions

Was this page useful?

Stack traces

Joe Martin

David Newell

Ian Vanagas