The wizard's bestiary

The SDK starts too late, more than once, or in a file that never runs.

Example: Browser init inside a component effect

Problem. Older posthog-js docs and most blog posts show a 'use client' PostHogProvider or _app.tsx that calls posthog.init in useEffect, often with a dynamic import to dodge SSR. Agents reproduce it from training data even when instrumentation-client.ts is available.

Impact. Init waits for hydration, so the first pageview and captures or flag reads made before the effect runs are dropped or throw. Every caller needs init guards and flags flicker. Same for React SPAs, where init belongs at module scope in main.jsx.

export function PostHogInitializer() {
  useEffect(() => {
    void import('posthog-js').then(({ default: posthog }) => {
      posthog.init(token, { api_host: host })
      window.posthogInitialized = true
      window.dispatchEvent(new Event('posthog_initialized'))
    })
  }, [])
}   // pages call posthog.capture() with no init guard

// instrumentation-client.ts runs before any component renders
import posthog from 'posthog-js'
posthog.init(process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN!, {
  api_host: '/ingest',
  defaults: '2026-01-30',
})
// components: useFeatureFlagEnabled('flag') works without PostHogProvider

Also catches:

• Fast models write Next.js init from memory into a lib file nothing imports, with a guessed env var and no defaults. The wizard has them follow the example's instrumentation-client.ts. init.md
• Same for iOS, where setup goes in a SwiftUI onAppear that runs many times and after early events. commandments.yaml
• Same for Flutter, where setup is not awaited before runApp, so the first frames send before the SDK is ready. commandments.yaml
• Older Next.js silently ignores instrumentation-client.ts, so PostHog never starts. The wizard checks the installed version and refuses Next.js below 15.3. posthog-best-practices/description.md
• The instrumentation-client file gets a .tsx or .jsx extension, so Next.js may not pick it up. instrumentation-client.ts
• App Router providers are added to a Pages Router project, so nothing mounts them.
• One init shape is used for every rendering mode or version, like Astro static, SSR, hybrid and view transitions, Nuxt 3.0 to 3.6 against 3.7+, or TanStack file and code routing. integration/config.yaml
• ES module imports run before the entry file's body, so modules that capture on load run before init. The wizard inits in its own module that every file imports. commandments.yaml
• The agent creates a provider file but never imports or mounts it, and the build stays green. The wizard checks that every created component is actually used. 3-revise.md
• Angular init in ngOnInit runs inside the zone, so replay's DOM observers trigger extra change detection. The wizard runs init outside the Angular zone.
• The Phoenix PostHog Plug is skipped or placed after the router, so request data and tracing headers never reach events. The wizard puts the Plug before the router. commandments.yaml
• React Router v6 and v7 framework, data and declarative modes each need init in a different entry file. The wizard picks the entry file for the detected mode. react-router-wizard-agent.ts
• Same for TanStack Router, where a file-based __root.tsx is created in a code-based app. tanstack-router/utils.ts
• Same for Nuxt, where @posthog/nuxt supports only 3.7+, so 3.0 to 3.6 need a plugin. integration/config.yaml
• Same for Laravel 11+, where middleware and providers moved to bootstrap/app.php. laravel-wizard-agent.ts
• Same for Next.js projects that use src/, where instrumentation-client.ts belongs beside src/app.
• Same for old framework or platform versions, which get current APIs and the latest SDK. frameworks
• Android setup in MainActivity reruns on every Activity and misses early events. The wizard sets up once in the Application class. commandments.yaml
• Kotlin Multiplatform setup copies the native one-argument shape and fails on Android. The wizard passes the right PostHogContext on each platform. commandments.yaml
• Astro 5 prerenders API routes by default, so server-side capture never runs, or the agent flips the whole site to SSR. The wizard opts out only the routes that capture. commandments.yaml

Code that needs a browser runs during server rendering, or server code ends up in the browser.

Example: Nuxt plugin also runs on the server

Problem. plugins/posthog.ts looks client-side, but Nuxt runs unsuffixed plugins in Nitro SSR too. Only the .client filename makes it browser-only.

Impact. SSR throws 'window is not defined' or initializes a browser SDK on the server.

// plugins/posthog.ts   (runs on server and client)
export default defineNuxtPlugin(() => {
  posthog.init(runtimeConfig.public.posthog.publicKey, {
    tracing_headers: [window.location.hostname],
  })
})

// plugins/posthog.client.ts   (client-only by filename)
export default defineNuxtPlugin((nuxtApp) => {
  const posthogClient = posthog.init(runtimeConfig.public.posthog.publicKey, {
    api_host: runtimeConfig.public.posthog.host,
    tracing_headers: [window.location.hostname],
  })
  return { provide: { posthog: posthogClient as PostHog } }
})

Also catches:

• Same for provider options like tracing_headers that read window in a root shell that also renders on the server. __root.tsx
• Same for SvelteKit, where +layout.ts and the +layout.svelte module script also run on the server. hooks.client.ts
• Same for Angular, where constructors, ngOnInit and app config also run during SSR. The fix is one DI service with a platform check. posthog.service.ts
• Same for Nuxt components that call the client with no guard, when there is no client during server render or no token. commandments.yaml
• A minimal init without the defaults date injects lazy scripts into the body and causes hydration errors. The wizard sets defaults so scripts go into the head. entry.client.tsx
• posthog-js is imported into server routes, where it has no window and sends nothing. The wizard uses posthog-node for server code. commandments.yaml
• The reverse. A posthog-node helper is imported into a use client file and ends up in the browser bundle. commandments.yaml
• posthog-js init options are passed to the posthog-node client, which has a different options type. commandments.yaml
• The posthog-js capture(event, props) shape is used in posthog-node, which takes one object with a required distinctId. todo.js
• The agent adds 'use client' or 'use server' to make a capture compile, which changes the file's rendering boundary. The wizard keeps the existing client and server split. commandments.ts
• An Astro, SvelteKit or React Router app on a Cloudflare adapter looks like Node, so Node-shaped code drops events on Workers. The wizard detects the Workers target from the adapter or wrangler config. cloudflare-detection.ts
• Same for process.env on Workers, which works only with nodejs_compat and, in Nuxt, only inside handlers. docs.yaml

The agent adds a second copy of something the project or an earlier step already set up.

Example: Second PostHog init beside the existing one

Problem. Agents add a PostHogProvider or init by reflex without searching for an existing provider or instrumentation-client.ts init, because most React examples pair init with a provider, including for flag hooks. Double init throws no error.

Impact. Two browser inits race to stamp $set_once properties like $initial_pathname, corrupting attribution and double-capturing pageviews. One multi-SDK customer saw about 165k blocked merges per day.

Variants.

• A second browser provider or init next to instrumentation-client.ts.
• A new client built just for a feature like metrics or AI.
• A migration that swaps an old vendor provider for a second PostHog one.

// instrumentation-client.ts
posthog.init(KEY, { api_host: '/ingest' })
// app/providers.tsx (always mounted)
useEffect(() => { posthog.init(KEY, { api_host: '/ingest' }) }, [])
// app/layout.tsx: <PHProvider>{children}</PHProvider>
// and <PostHogProvider> added again in the providers list

// instrumentation-client.ts: the one browser init
//IMPORTANT: Never combine this approach with other client-side PostHog
// initialization approaches, especially components like a PostHogProvider.
posthog.init(process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN!, { api_host: '/ingest' })

// components: hooks use the singleton, no provider needed
const on = useFeatureFlagEnabled('promo')
// audit init-not-duplicated: warning on 2+ browser inits, error if confirmed on one page

Also catches:

• Same for Flutter, where native auto-init from AndroidManifest.xml and Info.plist stays on beside the Dart setup. flutter-wizard-agent.ts
• The agent adds a PostHog client on OpenTelemetry paths that need none, or stacks a wrapper and an instrumentor on one provider. The wizard builds a client only on wrapper and manual paths and reuses an existing one. commandments.yaml
• A later task cannot see what earlier tasks did, so it adds identify or reset again. The wizard passes earlier steps' handoffs to every later task. agent-prompt-loader.ts
• The agent adds alias() next to identify() to be safe, which can block the identify merge. The wizard relies on identify() and keeps alias() for narrow cases. 3-identify-lifecycle.md
• The same milestone is captured in the browser and the API, so every conversion counts twice. The wizard captures key milestones once, on the backend. product-analytics.md
• A manual pageview component is added while defaults already capture history_change pageviews, so every navigation counts twice. The wizard keeps the automatic pageviews only. capture/description.md
• Custom page_viewed events are added on each screen mount, on top of automatic pageviews. instrument-product-analytics/description.md
• The full setup flow runs on a project that already has PostHog. The wizard detects the existing install and offers other programs first. intro-menu.ts

The agent misreads what kind of project it is in and sets up the wrong SDK or only half the app.

Example: Flutter repo misread as a native Android or iOS app

Problem. A Flutter repo has real Gradle, AndroidManifest, MainActivity.kt and Xcode files under android/ and ios/, so the first matching native or Java detector claims it.

Impact. posthog-android or the native source-map flow is wired into the shell. Dart screens, events and the web target are never tracked, and Java server projects can get claimed as Android.

// android/app/src/main/kotlin/.../MainActivity.kt inside a Flutter app
class MainActivity : FlutterActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    PostHogAndroid.setup(application, PostHogAndroidConfig(KEY, HOST))
  } // Dart code untouched
}

// constants.ts: flutter is ordered before kmp/swift/android; java comes after them
flutter = 'flutter',
// flutter detect: anchored to a key/value line, so '# sdk: flutter' and pure Dart don't match
/^\s*sdk:\s*flutter\s*$/m.test(pubspec ?? '')
// android + java detect():
// pubspec.yaml means Flutter - its android/ subtree would match below.
if (fs.existsSync(path.join(installDir, 'pubspec.yaml'))) return false;
// source maps: VARIANT_PRECEDENCE = ['react-native', 'flutter', 'android', 'ios', ...]

Also catches:

• A full-stack app gets only the browser SDK, so server events and errors are lost. The wizard sets up every runtime the app has. runtime-notes.ts
• A Gemfile or requirements.txt that only holds tooling is read as a server app, so release linking edits the wrong stack. The wizard ignores manifests that only carry tooling. setup-error-tracking.md
• A React Native or Flutter repo has ios/ and Gradle files, so it gets the native dSYM uploader instead of JS source maps. setup-error-tracking.md
• A pure Dart package with a pubspec.yaml gets a symbol upload, but it never builds an app. detect-agentic.ts
• A go.mod replace, comment or module line is read as a posthog-go dependency. detect-agentic.ts
• Upload is wired for stacks that cannot use it, like apps with no SDK or no build command. detect-agentic.ts
• A Kotlin Multiplatform app gets the native Android and iOS SDKs instead of posthog-kmp. The wizard adds posthog-kmp to commonMain and sets it up once in shared code. commandments.yaml
• Expo and bare React Native get the same recipe, so env access and native steps break. The wizard uses separate steps for Expo and bare React Native. utils.ts
• An API-only Rails app gets a browser snippet and even a new layout file. The wizard detects config.api_only and sets up the backend only. utils.ts
• Same for Replay vision, set up on an API with no pages or a KMP project with no replay support. replay-vision/index.ts
• Same for browser apps, where the generic Node fallback matched any package.json before the web detector. constants.ts
• Same for Gradle, where build.gradle alone does not say Android, KMP or a JVM server. java-wizard-agent.ts
• Same for a substring check on django or flask, which matches comments and plugin names. django-wizard-agent.ts
• Same for Go or Rust repos, where a lint or husky package.json matches the JS fallback first. constants.ts
• Detection listed only some manifests, so Flutter and Elixir projects matched nothing and the agent improvised. The wizard checks every supported manifest and lockfile. instrument-integration/description.md
• Same for existing installs, where SPM, CocoaPods, Gradle, NuGet, mix and Cargo installs look like no PostHog. self-driving/detect.ts
• Same for XcodeGen apps, which commit project.yml instead of a .xcodeproj. swift-wizard-agent.ts
• Same for LLM detection, which reads package.json and never requirements.txt or pyproject. features.ts
• The framework version is read from the package.json range, not the installed package, so version gates refuse valid projects. The wizard reads the version from node_modules. package-json.ts
• Full-stack apps get the browser metrics SDK, so server work goes unmeasured. The wizard picks the server metrics variant for full-stack apps. verify-sdk.md
• Same for logs, where a server OTLP exporter is added to a client-only app. logs.md
• A Rails or Laravel app gets only the server SDK, so views send no pageviews, replay or client errors. The wizard also adds the browser snippet to the layout. commandments.yaml

The agent writes code from old training data instead of following the framework's current conventions.

Example: Svelte 4 syntax written into a runes app

Problem. Training data is mostly Svelte 4, so agents write export let and on:click, and a JS build may not catch rune misuse, so the agent finishes without Svelte's own validator.

Impact. Components build but misbehave under runes, or the compiler rejects them.

<script>
  export let user;
  $: greeting = 'Hi ' + user.name;
</script>
<button on:click={consider}>
<!-- finishes without any Svelte validation step -->

<script>
  let { user } = $props();
  let greeting = $derived('Hi ' + user.name);
</script>
<button onclick={consider}>
<!-- use Svelte MCP (list-sections, get-documentation); always run
     svelte-autofixer on every new or modified .svelte file before finishing -->

Also catches:

• A WordPress token is hardcoded in the plugin or read from a custom .env file. The wizard reads it from constants in wp-config.php. commandments.yaml
• React code uses useEffect for derived state and callbacks, which causes extra renders and double PostHog calls. The wizard computes during render and calls from handlers. commandments.yaml
• The stock snippet assigns toString directly and throws on pages that freeze it, so PostHog never starts. The wizard uses a snippet that defines toString safely. generate-browser-snippets.js
• Svelte edits from stale memory loop on compiler errors without docs or an autofixer. commandments.yaml
• A mockito-style PostHog mock fails Flutter's platform token check, so every test fails. The wizard's example uses a fake that extends the platform interface. mocks.dart
• TypeScript and JavaScript files get mixed up, so files land with the wrong extension or syntax. The wizard checks for tsconfig.json and tells the agent which language to use. posthog-integration/index.ts
• An Android dependency is written in the wrong Gradle syntax or module. The wizard matches the file's DSL and edits the app module. commandments.yaml
• An Angular service is not a root singleton and reads process.env, so PostHog can init twice and env values are undefined. The wizard uses a root service, inject() and environment files. commandments.yaml
• WordPress code goes into the theme's functions.php, so a theme change removes it. The wizard puts it in its own plugin. commandments.yaml
• A WordPress plugin file has no ABSPATH guard, so a direct request runs it and exposes errors. The wizard adds the guard. commandments.yaml
• The agent plans a PostHogProvider in Vue, Svelte, Astro or Django, where none exists. The wizard uses a provider only when the framework's skill needs one. commandments.ts

The token sits in an env var, but the code that needs it runs where that variable is never loaded or exposed.

Example: Browser code reads an unexposed env var

Problem. The agent names variables from memory (POSTHOGKEY, REACT_APP*) instead of following the bundler's public-prefix rule. Server-side reads work, and the wizard's own react-router config still returns REACTAPP names for a Vite-based router, so nothing looks wrong until the browser runs.

Impact. Silent. The bundler strips the variable or there is no process.env in the browser, the token is undefined, and init is skipped, sends nothing or throws. Same for Astro, which exposes only PUBLIC_ variables and needs define:vars in inline scripts.

// lib/posthog.ts (Next.js), name from model memory
posthog.init(process.env.POSTHOG_KEY!, {
  api_host: process.env.POSTHOG_HOST,
})
// Vite app with CRA habits: process.env.REACT_APP_POSTHOG_KEY  (no process.env in the browser)
// Vue/Vite: import.meta.env.POSTHOG_KEY   (Vite only exposes VITE_*)

environment: {
  getEnvVars: (apiKey, host) => ({
    NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN: apiKey,
    NEXT_PUBLIC_POSTHOG_HOST: host,
  }),
}
// detectEnvVarPrefix(): next -> NEXT_PUBLIC_, react-scripts -> REACT_APP_, vite/TanStack -> VITE_PUBLIC_, SvelteKit -> PUBLIC_
// Nuxt: NUXT_PUBLIC_*   Vue: VITE_*   Angular (ngx-env): NG_APP_*

Also catches:

• Same for Angular, where the stock builder loads no .env and NGAPP only works with @ngx-env/builder. commandments.yaml
• Same for React Native, which needs react-native-config or expo-constants, not process.env. commandments.yaml
• Same for Express, Fastify, Hono, Ruby, Go, Spring and compiled binaries, which do not load .env on their own. error-tracking/init.md
• Same for Elixir, where config.exs runs at compile time. The token belongs in runtime.exs. runtime.exs
• Same for iOS, where Xcode scheme env vars exist only when you run from Xcode, so release builds crash or send nothing. commandments.yaml
• The deploy step, like docker run, compose or a PaaS config, never passes the token, so production runs with no analytics. The wizard adds the variables to the deploy step the same way the app's other variables are passed. wire-ci.md
• Same for Vercel, where only .env.local is written and production builds have no token. posthog-integration/index.ts
• A plain rollup or webpack config reads upload credentials from a .env file that nothing loads. The wizard loads dotenv in the bundler config. prompt.ts
• Same for vite.config, where loadEnv filters to VITE_ variables unless the third argument is an empty string. error-tracking-upload-source-maps/description.md
• Same for the Gradle upload task, which never reads .env. error-tracking-upload-source-maps/description.md
• Same for Flutter native builds, where the dotenv path points one level too deep from android/ or ios/. error-tracking-upload-source-maps/description.md
• Same for posthog-cli steps, where each call is its own child process, so inject gets no env file. error-tracking-upload-source-maps/description.md
• Laravel env() calls return null after config:cache, so production init gets no token. The wizard reads the token through config() in one service that inits once. commandments.yaml
• Same for the release ID, which the SDK reads with getenv(), so .env is ignored after config:cache. error-tracking-link-releases/description.md

The app runs with no token, a placeholder token, or a token from the wrong project.

Example: Empty or placeholder token used as fallback

Problem. Defaulting to '' or 'phc_placeholder' is the usual way to keep code compiling, satisfy a non-optional type and stop init from throwing, and the example apps did it too. Nothing fails: the SDK accepts the dead key and logs nothing.

Impact. Silent. Init runs with an empty or fake key, the build passes and no events arrive.

val token = System.getenv("POSTHOG_PROJECT_TOKEN") ?: ""
PostHogAndroid.setup(this, PostHogAndroidConfig(token))

// Astro example app
posthog.init(apiKey || '', { api_host: apiHost || 'https://us.i.posthog.com' })

if (!apiKey || !apiHost) {
  if (mode === 'development') {
    throw new Error(`${missingVariable} variable required by PostHog is missing or un-configured, this causes events to be silently missed. This error stops appearing once ${missingVariable} is configured`);
  }
} else {
  posthog.init(apiKey, { api_host: apiHost, defaults: '2026-01-30' });
}
// where a build has no env (mobile release), embed the real public token instead

Also catches:

• The agent takes the first project the MCP returns, so events land in the wrong project. The wizard asks the user when there is more than one project.
• The OAuth flow takes the first granted team and drops the project ID the caller asked for. project-resolution.ts
• The token is read as a required setting, so any environment without it crashes at boot or on every request. The wizard makes missing PostHog config a no-op with a dev warning.
• A Node start script uses node --env-file=.env, which exits on hosts that inject variables and have no .env file. error-tracking/init.md
• A Gradle build loads .env with no exists check, so fresh clones and CI fail to build. commandments.yaml
• The agent over-corrects to a quiet if (key) init() with no dev warning, so nobody learns why events are missing. commandments.yaml
• Same for Flutter web, where the docs placeholder token or an undefined window global ends up in static HTML. commandments.yaml
• A key name in .env looks done, so the agent keeps a stale or placeholder value. The wizard writes the correct value each time. posthog-integration/index.ts
• The key name is found in the committed .env.example, so the agent thinks it is set, or writes the real secret into that template. env-scan.ts
• A truthiness check accepts the .env.example placeholder phc_your_project_token_here as a real token. todo.php
• An existing init call reads a variable nobody defined, and the agent leaves it alone. error-tracking/init.md
• The public token is stored under legacy names like POSTHOG_API_KEY that nothing else sets. The wizard rejects those names unless the project already reads them. tools.ts
• Python init is guarded, but the module API still raises on capture when the key is None. The wizard sets a non-empty key with disabled so every call is a no-op. init.py

Env files are read from the wrong place or written in a way that breaks them.

Example: Agent edits .env files with its own tools

Problem. Read then Write, sed and echo >> are how a generic agent edits any file, so it re-types every line of .env.local to add one key. LLMs are poor at copying long random strings exactly, and the damage is one character in an unrelated secret.

Impact. Silent. Existing secrets are clobbered or changed and found hours later in another service. Plain reads also pull real secrets into model context and the gateway.

Read  .env.local   # DATABASE_URL, SUPABASE_KEY, AWS_* now in model context
Write { file_path: ".env.local", content: <whole file re-typed> }
# SUPABASE_KEY comes back 1 character different
$ sed -i 's/KEY=.*/KEY=phc_.../' .env.local   # same risk from the shell

check_env_keys({ keys: ['NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN'] })   // names only, never values
set_env_values({ filePath: '.env.local', values: {
  NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN: '<token>',
  NEXT_PUBLIC_POSTHOG_HOST: 'https://us.i.posthog.com' } })
// mergeEnvValues touches only matching lines
// harness denies Read/Write/Edit (and Grep targeting) any .env* basename; .env.example/.sample/.template/.dist stay writable

Also catches:

• A Python virtualenv named .env is a directory, so the key lookup crashes. The wizard treats a directory as a missing file. env-api-key.ts
• The key check reads only ./.env and misses keys in .env.local, so the agent gives up. The wizard scans every .env file and reports where each key is found. warehouse-source/index.ts
• New keys are written only to the ignored local file, so teammates and CI never learn them. The wizard adds the names to .env.example with empty values. init/description.md
• The agent adds .env.example itself to .gitignore, which hides the key list from version control. init/description.md
• The env writer misses lines written as export KEY=, so the key is declared twice. The wizard matches the export form and escapes key names.
• Piping a value to vercel env add stores a trailing newline in the token. The wizard writes the exact value with no newline. vercel.ts
• The agent writes to an existing file without reading it first, so the write fails or clobbers newer content. The wizard reads existing files just before editing and writes new files directly. posthog-integration/index.ts

Events or uploads go to the wrong PostHog region or to the wrong kind of host.

Example: Host defaults to US Cloud for EU projects

Problem. Docs and almost every example use us.i.posthog.com, and the agent has no rule for picking a region, so it writes the US host. The failure is silent because the SDK accepts the token and drops events on the wrong cluster.

Impact. An EU project's events go to the US ingest host and never appear. Nothing errors until a human notices.

# project actually lives on EU Cloud
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

posthog.init(token, { api_host: 'https://us.i.posthog.com' })

// harness: region comes from the OAuth token response (posthog_region), resolved once
HostResolution.fromRegion(region) // apiHost https://eu.i.posthog.com
// prompt: - PostHog Host: ${ctx.host.apiHost}
// skill: read `region` from projects-get: US -> us.i.posthog.com, EU -> eu.i.posthog.com
// unknown: ask "Are you on PostHog US Cloud or EU Cloud?" Do not assume US Cloud.

Also catches:

• Same for OTLP trace and metrics exporters, which get the US example URL instead of the configured host. tracing/description.md
• The app host, like us.posthog.com, is used as api_host. The wizard puts the ingestion host or proxy in api_host and the app host only in ui_host. app.component.ts
• The host is pasted into init as a literal, which freezes the region. The wizard reads the host from env vars and warns on unknown hosts. runtime-notes.ts
• The region is detected with a substring match, so lookalike hosts pass as EU. The wizard parses the URL and compares exact hostnames. gateway-session.ts
• The resolve-release step has no host, so EU and self-hosted releases are created on US Cloud. The wizard sets the host from the project. error-tracking-link-releases/description.md
• posthog-cli is pointed at the ingestion host, so uploads are rejected. The wizard sets POSTHOG_CLI_HOST to the app host. error-tracking-upload-source-maps/description.md

The browser cannot reach PostHog because a content security policy, proxy or network rule gets in the way.

Example: Browser SDK sends straight to PostHog, no proxy

Problem. The quickstart snippet uses the public ingest host and works on the agent's machine. Ad-blocker loss only shows up as under-counting in production.

Impact. Silent: ad and tracking blockers drop a meaningful share of browser events, flags and replay.

posthog.init(import.meta.env.VITE_PUBLIC_POSTHOG_PROJECT_TOKEN, {
  api_host: 'https://us.i.posthog.com', // blocked by ad blockers
})

posthog.init(import.meta.env.VITE_PUBLIC_POSTHOG_PROJECT_TOKEN, {
  api_host: '/ingest',
  ui_host: 'https://us.posthog.com',
  defaults: '2026-01-30',
})
// plus framework rewrites: /ingest/static, /ingest/array -> assets origin; /ingest -> us.i.posthog.com

Also catches:

• A Rails app gets a CSP nonce, but the CSP initializer still blocks PostHog's hosts. The wizard adds the PostHog hosts to the CSP initializer. init/description.md
• Replay loads the app's fonts and styles from origin, but those responses lack CORS headers, so replays render unstyled. The wizard adds crossorigin and the CORS header. session-replay.md
• A bundled posthog-js still lazy-loads replay, surveys and the toolbar from the assets CDN, which script-src blocks. The wizard extends every CSP directive the SDK needs in one pass. init/description.md
• Same for session replay, which runs in a blob: worker that worker-src must allow.
• Review accepts a handoff that says "CSP handled" and never opens the policy. integration-v2/init.md
• A hand-written proxy sends /array remote config to the API host, so config goes stale. The wizard routes /static and /array to the assets host. hooks.server.ts
• Same for EU projects, where the main target moves to EU but the asset rules still point at the US assets origin. commandments.yaml
• A hand-written proxy passes the original Host header and client IP through, so requests fail or lose geolocation. The wizard sets host and x-forwarded-for explicitly. hooks.server.ts
• The proxy is set only in the dev server config, so production has no /ingest route. The wizard adds the same routes to the production host config. posthog-best-practices/description.md
• With a proxied api_host and no ui_host, toolbar and replay links point at the proxy. The wizard always sets ui_host. instrumentation-client.ts
• Existing i18n or auth middleware redirects the /ingest path, so events and flags 404. The wizard excludes the proxy path from the middleware matcher.
• The proxy is set up on one host but not on a second site, so one domain under-reports. The wizard checks direct and proxied traffic per host. checks.md
• Flutter release builds have no INTERNET permission or network entitlement, so they send nothing. The wizard adds the Android permission and the macOS entitlement. AndroidManifest.xml
• Same for sandboxed macOS apps, where the agent turns the sandbox off instead of adding the network entitlement. commandments.yaml
• SvelteKit's default relative asset paths break replay of SSR pages. The wizard sets paths.relative to false. commandments.yaml

Queued events are dropped because the process, request or page ends before the SDK sends them.

Example: Short-lived handler returns before batched events send

Problem. posthog-node capture() only enqueues, and on a long-lived local dev server the batch still goes out, so the bug never shows locally. Old docs and the old commandment said not to set flushAt or flushInterval in 'long-running servers', which agents applied to Next.js, Nuxt, SvelteKit, Astro and TanStack Start route handlers.

Impact. Silent: on serverless or edge the function freezes on return before the batched HTTP send, so server events are dropped. Low-traffic endpoints lose most events.

Variants.

• Route handlers on serverless or edge hosts.
• Server error hooks like SvelteKit handleError.
• AWS Lambda handlers, and Celery, Sidekiq or BullMQ jobs.

// lib/posthog-server.ts
const posthog = new PostHog(token, { host })   // default batching: 20 events / 10s

export async function POST(request: Request) {
  posthog.capture({ distinctId: username, event: 'server_login' })
  return NextResponse.json({ success: true, user }) // returns before the send
}

// lib/posthog-server.ts
new PostHog(token, { host, flushAt: 1, flushInterval: 0 })

// api/auth/login/route.ts
posthog.capture({ distinctId: username, event: 'server_login' })
// This handler is short-lived; flush so the enqueued events send before it returns
await posthog.flush()
return NextResponse.json({ success: true, user })

Also catches:

• A server SDK client is built in every request, so it leaks and loses buffered events. The wizard uses one module client for every handler. init/description.md
• Same for Django, where the client is made in settings.py, a view or at import instead of once in AppConfig.ready. commandments.yaml
• A Statsig migration maps shutdown() to PostHog in browser code, where posthog-js has no teardown. The wizard maps it only in clear server teardown handlers. mapping.md
• Same for Cloudflare Workers, where the isolate can end as soon as the Response returns. cloudflare-detection.ts
• Same for a serverless MCP handler that relies on a SIGTERM flush, which never fires on Vercel, Workers or Lambda. mcp-analytics/description.md
• A per-request server client is never shut down, so its batch never sends. The wizard calls shutdown() on per-request clients. commandments.yaml
• The opposite case. A shared module client is shut down in every request, so later requests drop their events. commandments.yaml
• A long-running server never flushes on stop or deploy, so queued events are lost. The wizard wires posthog.shutdown() to server shutdown. commandments.yaml
• Same for Laravel queue:work, Horizon and Octane workers, which never destruct the client. commandments.yaml
• Same for Go, where log.Fatal calls os.Exit and skips the deferred client.Close().
• A minimality review deletes an unused shutdown helper. The wizard treats shutdown wiring as required and wires it to process exit.
• A CLI or job exits before posthog-node sends its queue. The wizard awaits shutdown() before exit. posthog-best-practices/description.md
• Same for metrics, which flush on an interval that a cron job or script never reaches. metrics/description.md
• Same for OpenTelemetry trace spans. Serverless handlers flush per invocation and shut down only at process exit. ai-observability/references/3-instrument.md
• Same for LLM scripts, where the wrapper hides the capture, so the agent never sees a call that needs a flush. commandments.yaml
• Same for PHP CLIs, cron jobs and WordPress hooks, where the destructor may never run. commandments.yaml
• Same for a Python MCP server, which needs both analytics.flush() and posthog.shutdown() to drain its two queues. mcp-analytics/description.md
• A logout form submit navigates away before the capture sends. The wizard sends the logout event with sendBeacon, then resets.
• Each framework exposes waitUntil on Workers in a different place, so a remembered pattern is undefined. The wizard imports waitUntil from cloudflare:workers. docs.yaml

The agent writes SDK calls from memory or copies the shape of a different SDK, so the code fails or does nothing.

Example: Scaffolding features the Rust or Java SDK lacks

Problem. Training data and JS docs describe alias, replay, surveys and exception autocapture, so the agent assumes every SDK has them.

Impact. Code that does not compile or silently does nothing, and a report claiming capabilities the user lacks.

// Rust
client.alias(old_id, new_id)?;          // no alias in posthog-rs
// Java Spring
PostHog.builder(key).enableExceptionAutocapture(true)  // not in posthog-server

Rust: no identify/alias helper, no surveys or session replay; set person props by inserting a $set property on an event.
Java server SDK: no automatic error tracking, surveys or session replay; do not promise or scaffold them. Identify via userProperty(...) on a capture; report failures as an explicit capture event.

Also catches:

• Enabling web vitals writes a fresh capture_performance object, which drops existing keys. The wizard keeps existing keys and adds web_vitals. remediation.md
• Products are turned on in project settings while client init options still turn them off. The wizard removes init options that override the project setting. 3-enable-products.md
• Same for Elixir, which has no capture_exception or identify and captures errors through a Logger handler. burrito_controller.ex
• Same for Android, where the agent invents a PostHog.getInstance() accessor that never existed. BurritoApp.kt
• Same for AWS Bedrock, where the agent invents a PostHog wrapper client. Bedrock needs OpenTelemetry instrumentation. ai-observability/references/2-install.md
• Same for Go, where the agent fakes identify with a Capture call named $identify.
• The Ruby gem is required as posthog-ruby, but its library file is posthog. The wizard writes require 'posthog'. commandments.yaml
• Two documented SDK setups are mixed, so Python events go to an unconfigured default client. The wizard follows one setup all the way through. capture-exceptions.md
• Python is configured through module globals like posthog.api_key, so instance options are never set up. commandments.yaml
• posthog-php capture is called with positional arguments and throws a TypeError. The wizard passes one array with distinctId and inits once. commandments.yaml
• Same for Ruby, where capture takes keyword args but capture_exception takes positional args. commandments.yaml
• Same for Flutter, where captureException needs named args and an explicit stackTrace. error-tracking-upload-source-maps/description.md
• Same for Python SDK v6, which removed identify() and the positional capture(distinct_id, event) shape. commandments.yaml
• Elixir capture without a distinct_id returns an error tuple that nobody checks, so the event is dropped. The wizard always passes distinct_id. commandments.yaml
• Kotlin Multiplatform code uses native imports and the wrong context, so it does not compile or Android has no usable SDK. The wizard uses the com.posthog.kmp imports and the right context per platform. commandments.yaml
• The agent patches a private SDK method by its source name, which the production bundle renames. The wizard uses public APIs only.
• The agent hand-writes identity and exception middleware the SDK already ships. The wizard adds the SDK's own middleware, like PosthogContextMiddleware for Django. commandments.yaml
• Same for Rails, built like a plain Ruby script with PostHog::Client.new instead of posthog-rails. commandments.yaml
• Same for ASP.NET, where a client is built in each controller instead of the PostHog.AspNetCore DI registration. commandments.yaml
• Same for MCP servers, where each tool handler gets a capture instead of @posthog/mcp. mcp-analytics/description.md
• Same for Flutter, where lifecycle events are hand-rolled though the SDK captures them since 5.23.0. posthog.dart

The SDK is installed with the wrong version, the wrong tool, or only half its setup.

Example: SDK version typed from memory

Problem. Editing the manifest directly feels quicker than running the package manager, and the model trusts the version numbers it remembers. A version that was never published fails only later, at install time, and an old remembered version installs without any warning.

Impact. A version that was never published makes the whole install fail with ETARGET, and the build step cannot recover from a bad manifest. Each new guess fails again. A remembered old version pins a stale SDK that still has bugs fixed upstream.

"dependencies": {
  "posthog-js": "^1.96.0",     // remembered, stale
  "posthog-node": "^5.99.0"    // never published
}
// npm error code ETARGET
// npm error notarget No matching version found for posthog-node@^5.99.0
# pubspec.yaml: posthog_flutter: ^4.0.0   # remembered, not resolved

npm install posthog-js posthog-node   # bare names, manager writes real ^x.y.z + lockfile
composer require posthog/posthog-php
bundle add posthog-ruby
flutter pub add posthog_flutter
# ETARGET / yanked release: reinstall by bare name, do not guess pins
npm view posthog-js version           # audit: installed vs latest

Also catches:

• posthog-rs adds its async client to a crate with no async runtime, so the build fails. The wizard uses the blocking client when no runtime is found. rust-wizard-agent.ts
• The SDK is wrapped in a guarded require to get a green build, so it never starts. The wizard imports and inits the SDK directly. runtime-notes.ts
• The SDK pin is lowered so a local install passes, or a major is jumped under existing calls. The wizard keeps the minimum and records a follow-up. error-tracking-link-releases/description.md
• Same for Go, where the agent raises the project's go directive to make the bridge install. ai-observability/references/1-begin.md
• The agent refuses to declare the SDK when it cannot find a version. The wizard declares it at a known-good caret version. install.md
• An unquoted version specifier in pip install becomes a shell redirect. The wizard installs from the requirements file or quotes the specifier. commandments.yaml
• Same for the com.posthog.android Gradle plugin, which has its own version numbers, separate from the SDK. error-tracking-upload-source-maps/description.md
• Same for @posthog/cli, where a remembered old release installs but rejects the flags from newer docs. error-tracking-upload-source-maps/description.md
• The SDK version floor is older than the APIs the new code uses, so calls fail or do nothing. The wizard raises the floor to the version that added the API. Gemfile
• Same for posthog-js under @posthog/react, where the loose peer range keeps an old version that ignores tracing_headers. package.json
• Same for the release ID, which SDKs below the floor drop with no error. error-tracking-link-releases/description.md
• Same for @posthog/mcp, where old versions reject MCP SDK v2 servers and ignore newer options. mcp-analytics/description.md
• The SDK is installed with npm in a pnpm or yarn project, so a second lockfile appears. The wizard detects the package manager and uses it. package-manager.ts
• Same for Python, where pip runs outside the uv, Poetry, Pipenv or venv environment the project uses. python/utils.ts
• Same for pip install, which does not record the package in requirements, so deploys fail with ImportError. framework-config.ts
• Commands use bare python and pip, which many hosts do not have. The wizard uses python3 and the project's venv. runtime-notes.ts
• A blocked install leads the agent to change nothing or hand-edit the manifest, and the run still reports success. The wizard allows the managers' real install commands and explains denials. bash-fence.ts
• Install errors the integration did not cause send the agent into a retry spiral with --force and lockfile deletion. The wizard tries once, declares the SDK and reports the error. install.md
• Same for an AI wrapper forced past a peer conflict with --legacy-peer-deps, which then fails at runtime. integration-v2/review.md
• posthog-react-native is installed without its peers, so ids reset and surveys crash. The wizard installs the storage, svg and device peers. commandments.yaml
• go.mod or Cargo.toml is hand-edited, so checksums are missing. The wizard uses go mod tidy and cargo add. go-wizard-agent.ts
• The install runs in the background while the build starts. The wizard runs installs in the foreground and waits. runtime-notes.ts
• A Swift package is added to project.pbxproj with only one of the three objects Xcode needs. The wizard adds all three linked objects. commandments.yaml
• Same for XcodeGen projects, where the next generate rebuilds project.pbxproj from project.yml and drops the package. commandments.yaml
• Same when Xcode has the project open, because it rewrites project.pbxproj on its next save. swift-wizard-agent.ts
• An old posthog-go pin never sends the data symbolication needs. The wizard upgrades posthog-go to 1.22.0 or later in the same step. error-tracking-upload-source-maps/description.md
• Flutter's native iOS, macOS and Android minimums stay below the SDK floor, so native builds fail. The wizard raises them where they are too low. commandments.yaml

Events are tied to an id that is missing, shared, personal or changes over time, so people split or merge wrongly.

Example: Literal anonymous fallback pools all users

Problem. A ?? 'anonymous' fallback or a constant 'server'/'backend' id satisfies the SDK's required distinctId and the type checker, so it looks like defensive coding and never errors. The pooled person only shows up later in data.

Impact. Silent: every logged-out visitor or unattributed server event lands on one giant person, corrupting counts, funnels, retention and person merges.

signIn: async ({ user, account }) => {
  const distinctId = user?.id ?? user?.email ?? "anonymous";
  posthog.identify({ distinctId, properties: { name: user?.name, email: user?.email } });
  posthog.capture({ distinctId, event: "server_sign_in" });
}
// go
client.Enqueue(posthog.Capture{DistinctId: "server", Event: "order_created"})

callbacks: {
  session({ session, token }) {
    if (session.user && typeof token.sub === "string") session.user.id = token.sub;
    return session;
  },
},
// identify only when the stable id is a string; otherwise skip and stay anonymous
if (typeof session.user?.id === 'string') posthog.identify(session.user.id, { email: session.user.email })
// truly system-level: no person profile
posthog.capture({ distinctId: 'cron', event: 'nightly_sync', properties: { $process_person_profile: false } })

Also catches:

• Email is used as the distinct id, so PII is every event's identity and a changed email splits a person. The wizard identifies with the stable user id and sets email as a person property. identify/description.md
• Example READMEs still pass user.email, so the agent copies the README shape over the fixed example code. example-apps
• A session id or a fresh UUID per login is passed to identify, so every login creates a new person. The wizard uses the app's stable user id. identify/description.md
• Same for CLIs, which get a uuid4() or the OS username on every run instead of one id saved per install. todo.py
• Identify reads a field the backend never sends to the frontend, so it never fires or gets undefined. The wizard checks the id reaches the call and exposes it at the source if not.
• A missing id is wrapped in String() and becomes the string undefined, which pools every user. The wizard skips identify when there is no id. identify/description.md
• Same for PHP, where (string) binds tighter than ??, so a null id becomes an empty string and the fallback never runs.
• Same for apps with no login, where the agent invents identify("user") or ships a DISTINCT_ID placeholder instead of capturing personless. identify.md
• Same when the stable id is not in scope at a job or webhook, and the guess is mentioned only as a vague caveat. capture.md
• Same for LLM events, copied from a skill example that hardcoded user_123. ai-observability/references/3-instrument.md
• Same for stateless MCP transports, which get a constant distinctId and a fresh sessionId per call. mcp-analytics/description.md
• Stripe metadata gets a customer or org id that differs from the identify id, so revenue never joins the person. The wizard finds the id passed to identify and threads it into Stripe. revenue-analytics/description.md
• A TODO placeholder string is written to Stripe as the distinct id. revenue-analytics/description.md
• The app never calls identify, so any id mapping for Stripe points at no real person. revenue-analytics/detect.ts
• The person link is added only on Stripe Customer creation, so PaymentIntents, Subscriptions and Invoices have none. The wizard adds the metadata to each object that creates revenue. revenue-analytics/description.md
• next-auth's default session has no user id, so identify gets undefined. The wizard adds the id in the session callback. identify/description.md

identify, reset or person properties run at the wrong moment, so events land on the wrong person.

Example: Returning logged-in users never identified

Problem. Docs and most example apps show identify() inside the login handler, so the agent wires it there. Sessions restored from a cookie, stored credentials or app restart skip that handler, and nothing signals the gap.

Impact. Silent: returning sessions (new tab, cleared PostHog storage, new device with a live server session) stay on anonymous distinct ids, splitting one user across anonymous and identified persons.

async function onSubmit(values) {
  const user = await login(values)
  posthog.identify(user.id, { email: user.email })   // only path
}
// cookie-restored sessions auto-redirect past this handler

// on login success AND on any load where a session already exists
useEffect(() => {
  if (user && posthog.get_distinct_id() !== user.id) {
    posthog.identify(user.id, { email: user.email })
  }
}, [user])

Also catches:

• First-touch properties are written with $set, so every later identify overwrites them. The wizard writes them with $set_once. 2-attribution-fix.md
• group() runs on render with an unstable key, so groups multiply. The wizard calls it on login or org switch with the stable org id. 3-identify-lifecycle.md
• Capture is written before identify is settled, so each call site invents its own attribution. The wizard runs capture after identify and reads its handoff. capture.md
• Login is tracked as an event, but identify is never called, so every event stays anonymous. The wizard calls identify on login. commandments.yaml
• Identify sits on a late page mount like settings or profile, so startup captures and flag reads run anonymously. audit/references/3-identification.md
• $set is attached to every capture, which bloats person properties and overwrites first-touch values. The wizard sets person properties in identify, with first-touch values in $set_once. 3-identify-lifecycle.md
• Logout never calls reset(), so the next user on the device inherits the previous person. The wizard resets on logout. commandments.yaml
• reset() runs whenever there is no user, including every first visit. The wizard resets only when an identified user logs out. commandments.yaml
• Reset runs right before identify on login, which throws away the anonymous id that identify would link. commandments.yaml
• Identify fires on every navigation or render. The wizard guards it so it runs once per user. identify.md
• The logout event is captured after reset, or the login event before identify, so it lands on the wrong person. The wizard captures logout before reset and login after identify. auth_state.dart
• Same on the server, where the logout event reads its id from the session the handler just cleared. commandments.yaml
• Same for Django login, where the context middleware read request.user before login() ran. commandments.yaml
• Same for FastAPI login, where the request context was built from the cookie before the handler made the session. main.py
• Users are identified on the server or on both sides, so pre-login browser activity never merges. The wizard identifies once in the browser and passes the browser ids to the server. nuxt-4/README.md
• Same for Rails, where posthog-rails identifies in the sessions controller and the posthog-js snippet never does. ruby-on-rails/README.md
• A server capture with $set makes the person look identified, but no $identify event fires and nothing merges. audit-identify/references/5-server-sdk.md
• distinct_id is passed as a capture property, so only that one event lands on the user.
• identify is called twice with two different ids, which blocks the merge. The wizard calls identify once with the stable internal id. 2-identify-fix.md

Server code captures events and errors outside the request's user context, so they carry no person.

Example: Django context middleware placed before authentication

Problem. Agents put new middleware at the top of MIDDLEWARE by habit and the docs snippet just says 'add it'. Request.user is not populated yet, and nothing errors.

Impact. Silent: every request context is personless, so server events are not attributed to the logged-in user.

MIDDLEWARE = [
    'posthog.integrations.django.PosthogContextMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
]

MIDDLEWARE = [
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'posthog.integrations.django.PosthogContextMiddleware',  # after auth
]

Also catches:

• Rails job failures are autocaptured with no user. The wizard adds the posthog_distinct_id DSL to the job. example_job.rb
• Per-request user and thread ids are put on the OpenTelemetry Resource, so every request shares one identity. The wizard sets them per request in telemetry metadata.
• Elixir context is set per process, so a spawned Task loses it. The wizard sets context inside the capturing process or passes distinct_id. commandments.yaml
• Python new_context() is opened around every capture call. The wizard binds identity once per request in a middleware. posthog-best-practices/description.md
• Node errors are captured with no user because captureException has none in scope. The wizard wraps each request in withContext. posthog-best-practices/description.md
• PHP error autocapture has no context_provider, so exceptions get a random id. The wizard adds a context_provider that returns the user id. todo.php
• FastAPI has no PostHog middleware, so bare captures in handlers are personless. The wizard adds a small ASGI middleware that binds identity. middleware.py

The browser, server, other hosts or app extensions each get their own identity, so one user's activity never joins up.

Example: Server events use a different id than the browser

Problem. Server SDKs require a distinctId on each call, so the agent fills it from whatever is local (username, IP, body field, email, random UUID) and never forwards the browser's distinct id and session id.

Impact. Silent: one user becomes two persons and server events are missing from the browser session and its replay.

// client identifies with user.id
fetch('/api/checkout', { method: 'POST' })
// server
posthog.capture({ distinctId: crypto.randomUUID(), event: 'checkout_completed' })
// or distinctId: username / req.ip / user.email / a body field

// browser: init with tracing_headers: ['api.example.com'] adds both headers
// middleware: bind the browser's ids once per request
const sessionId = request.headers.get('X-POSTHOG-SESSION-ID')
const distinctId = request.headers.get('X-POSTHOG-DISTINCT-ID')
return posthog.withContext(
  { sessionId: sessionId ?? undefined, distinctId: distinctId ?? undefined }, next)
// route handler: no distinctId argument
posthog.capture({ event: 'burrito_considered' })

Also catches:

• tracing_headers gets window.location.host, which includes the port, so no headers are sent in dev. The wizard uses hostname. posthog.astro
• Tracing headers use an internal option name, a hand-written fetch wrapper, or an SDK too old for the option. The wizard uses the public tracing_headers option on a version that supports it. identify/description.md
• A marketing site and the app keep separate cookies, so UTMs never reach signup. The wizard enables cross-subdomain cookies on the parent domain. 3-attribution-config.md
• Same for a form API route on a site with no login, which keys events on the submitted email. capture/description.md
• Same for tracing spans, which need the browser distinct id and session id attributes to join a person and replay. tracing/description.md
• Outbound calls drop the traceparent header, so downstream spans start new traces. The wizard forwards traceparent. tracing/description.md
• iOS widgets and extensions get their own anonymous id. The wizard sets a shared app group in every target. commandments.yaml

The events that matter most are captured in a place that can miss or fake them, or not captured at all.

Example: Payment, webhook and auth events only in the browser

Problem. The agent follows the client SDK quickstart and instruments UI handlers. API routes, webhooks and Server Actions have no visible button, so it never opens them.

Impact. Silent: business-critical events such as payments and signups are lost to ad blockers, closed tabs, and flows that never touch the browser.

// Checkout.tsx
posthog.capture('checkout_clicked')
// app/api/webhooks/stripe/route.ts -> no PostHog call at all

// payment webhook handler
const posthog = getPostHogClient()   // posthog-node
posthog.capture({ distinctId: userId, event: 'payment_succeeded',
  properties: { plan } })
await posthog.flush() // shared client in a per-request handler

Also catches:

• Signup and purchase are left to autocapture, so funnels have no milestones. The wizard captures key business events by name. product-analytics.md
• User actions are captured from effects or render, so they fire on mount and twice under StrictMode. The wizard captures in the event handler after success. commandments.yaml
• A success event fires before the server confirms, so failed requests count. The wizard captures after the response succeeds.

Events are named or shaped in a way that makes them hard or impossible to analyze.

Example: Event names built from variables

Problem. Interpolating an id or label into the name feels expressive, DRY and type-checks fine. Nothing warns that each distinct string becomes its own event definition.

Impact. Silent: unbounded event and property definitions that cannot be charted, funneled or cleaned up, and audits cannot resolve what is captured.

posthog.capture(`clicked_${button.id}`, {
  [`${field}_value`]: value,
})
posthog.capture('plan_selected', { [`plan_${id}`]: true })

posthog.capture('button_clicked', {
  button_id: button.id,
  field_name: field,
  value,
})
// "Never generate event names or property keys dynamically. Put variable data in property values."

Also catches:

• Events are captured with no properties, so they can only be counted. The wizard adds the properties needed to break them down. commandments.yaml
• Filler events are invented to reach a suggested count. The wizard treats the count as a rough guide and never invents events. capture/description.md
• The first PR instruments every valuable event at once, which is hard to review and goes past the 50 event plan limit. capture/description.md
• Every repository and service method gets a capture in layered backends like ASP.NET. commandments.yaml
• New event names ignore the project's existing names, so actions get near-duplicate twins. The wizard scans existing captures and reuses their names. capture/description.md
• Same for metrics, where user ids, emails and raw URLs as attributes explode the series count. metrics/description.md
• Same for span names that hold real paths or ids, so operations never aggregate. tracing/description.md
• The same number is sent as a number at one site and a string at another, so aggregates drop rows. The wizard converts values to numbers. 5-report.md
• Demo events are seeded with real-looking ids and no marker, and PostHog events cannot be deleted. The wizard tags seeded events and backdates them, only on empty cloud projects. seed-events.ts

Pageviews and screen views are counted twice, split, or never sent.

Example: Client-side route changes send no pageviews

Problem. A plain posthog.init looks complete because the first load produces a $pageview. The agent never tests a soft navigation, and older docs taught a hand-rolled PostHogPageView component.

Impact. Silent: only the first hard load generates a $pageview. Later router or View Transition navigations are lost. Setting the defaults option turns on history_change pageviews.

posthog.init(token, { api_host: host })
// router push / View Transitions produce no $pageview

posthog.init(token, {
  api_host: host,
  capture_pageview: 'history_change',   // or defaults: '2026-01-30'
})

Also catches:

• Pageleave capture is off in an SPA, so bounce rate and session time under-report. The wizard turns on pageleave with history_change pageviews. remediation.md
• The same page is tracked under several hosts, so its numbers split. The wizard reports the path and hosts so you can fix it. checks.md
• A state-driven SPA never changes the URL, so only the first load counts as a pageview. The wizard captures a pageview on each in-app page change. commandments.yaml
• Astro view transitions skip page reloads, so later navigations send no pageviews and listeners stop. The wizard uses history_change pageviews and the astro:page-load event. commandments.yaml
• Inline init re-runs on every soft navigation. commandments.yaml
• Listeners bound once on first load are lost after a ClientRouter page swap. commandments.yaml
• WordPress pageviews are captured from PHP, so cached pages send nothing. The wizard captures pageviews with the browser snippet. commandments.yaml
• Expo Router has no NavigationContainer, so screens are never tracked. The wizard captures screens from the router's pathname. commandments.yaml
• Same for Flutter, where PosthogObserver is skipped or routes have no names. commandments.yaml
• Same for React Navigation v7, where the provider wraps NavigationContainer and the screen hook fails. commandments.yaml
• Same for SwiftUI, where captureScreenViews gives internal view identifiers. commandments.yaml
• Same for Android, where activities with no android:label show blank or class-name screens. commandments.yaml
• TanStack Router pageviews use a useEffect, so they double or go missing. The wizard uses the router's navigation events. commandments.yaml

Marketing attribution like UTMs and ad click ids never reaches the events that need it.

Example: Conversion events carry no attribution

Problem. Person-level $initialutm* properties exist, so the agent assumes conversions are attributed. The event itself carries none of those values.

Impact. Event insights cannot slice signups or purchases by utm_campaign or referring domain at event time. Only a person-property breakdown works, losing event-time fidelity.

posthog.capture('signed_up', { plan })

const a = getAttribution()   // utm_*, gclid, referrer read at landing
posthog.capture('signed_up', {
  plan,
  utm_source: a.utm_source,
  utm_campaign: a.utm_campaign,
  gclid: a.gclid,
})

Also catches:

• Ad click ids like gclid, fbclid and msclkid are assumed covered, but only UTMs are captured automatically. audit-attribution/references/2-attribution-fix.md
• The landing page strips UTMs before PostHog starts, so the first pageview has no campaign data. The wizard checks that init runs before any query cleanup or redirect. 2-attribution-fix.md
• Same for social sign-in, where the OAuth round trip drops the query string. audit-attribution/references/2-attribution-fix.md
• Same for wizard setup links, where agents strip utm parameters as noise. warehouse/description.md

The setup sends data that costs money but adds no value, like dev traffic, needless person profiles and empty recordings.

Example: person_profiles 'always' on mostly anonymous traffic

Problem. 'always' sounds like the complete, safe choice, and the cost difference is not visible in code.

Impact. Every anonymous event creates a person profile and is billed as identified, at roughly four times the price.

posthog.init(key, {
  api_host: '/ingest',
  person_profiles: 'always',
})

posthog.init(key, { api_host: '/ingest' })
// default 'identified_only'; keep 'always' only when identified traffic >= 90%

Also catches:

• Dev and staging send events to the production project. The wizard inits only in production or uses a separate project. 3-events-optimize.md
• Same for test runs and CI, which import the app entry and burn quota on flag requests and replays. audit-feature-flags/references/3-feature-flags-optimize.md
• Same for copy and dead-click autocapture, which bill every event while heatmaps already collect dead clicks for free. audit-autocapture/references/3-autocapture-optimize.md
• Session replay records bounces and CI test runs. The wizard sets a minimum duration and turns replay off in tests. 2-session-replay-fix.md
• Every server event creates or updates a person, which overwrites browser properties and bills each event as identified. The wizard turns off person processing on system events only.

A framework's own error handler catches exceptions before PostHog sees them, or PostHog's handler hides the framework's.

Example: Flask error handlers hide exceptions from PostHog

Problem. Agents trust SDK autocapture, but Flask turns exceptions into responses in its own errorhandler first, so the exception is handled and autocapture never fires.

Impact. Silent: Flask 500s never reach Error Tracking.

@app.errorhandler(500)
def internal_server_error(e):
    return render_template('errors/500.html'), 500  # PostHog never sees e

@app.errorhandler(Exception)
def handle(e):
    if isinstance(e, HTTPException):
        return e
    posthog.capture_exception(e)
    return render_template('500.html'), 500
# routes.py example adds user context:
#   with new_context(): identify_context(str(current_user.id)); posthog.capture_exception(e)

Also catches:

• ASP.NET exception middleware captures and returns a 500 instead of rethrowing, which bypasses the app's own error handling. The wizard captures and rethrows. commandments.yaml
• Same for Express, Fastify and Koa, whose error middleware catches route errors first. commandments.yaml
• Same for the React Router ErrorBoundary, which catches render errors before window.onerror. root.tsx
• Same for Vue, which only logs component errors in production unless app.config.errorHandler is set. main.ts
• Same for Nuxt, where the fix is the vue:error app hook. posthog.client.ts
• Same for SvelteKit, which sends handled and server errors through handleError hooks. hooks.client.ts
• Same for Rails, where rescue_from and ActiveJob failures count as handled. commandments.yaml
• Same for CLI scripts, where a catch-all around main() prints and exits. todo.py
• Same for WordPress, where recovery mode renders its page before PostHog sees the fatal. commandments.yaml

Exception capture is never turned on, or errors are sent in a shape Error Tracking cannot use.

Example: Exception autocapture left off at init

Problem. The agent treats 'add PostHog' as analytics only and copies an analytics-only init snippet. Capture_exceptions is opt-in, so nothing breaks until a user opens an empty Error Tracking tab.

Impact. Silent: uncaught browser errors never reach PostHog. Users conclude Error Tracking does not work. Same for Python, where the option is enable_exception_autocapture.

posthog.init(apiKey, { api_host: '/ingest', defaults: '2026-01-30' })
// no capture_exceptions, no captureException anywhere
// React: <PostHogProvider apiKey={key} options={{ api_host: '/ingest' }}>

posthog.init(apiKey, {
  api_host: '/ingest',
  defaults: '2026-01-30',
  capture_exceptions: true, // unhandled exceptions -> Error Tracking
})

Also catches:

• Exceptions are captured as strings or with ids in the message, so issues do not group. The wizard captures a real Error with a stable message and keeps the cause.
• Exceptions are sent as hand-built $exception events, so Error Tracking shows no usable issue. The wizard uses the SDK's captureException. error-tracking.md
• Same for Go, where the agent enqueues a generic Capture instead of NewDefaultException or the slog handler. commandments.yaml
• Same for iOS, where the Swift example app still shows a custom event and errorTrackingConfig stays off. commandments.yaml
• The exception step reads the SDK install page, which says nothing about error hooks. The wizard gives each platform its error tracking install page. error-tracking-step/config.yaml
• Same for Flutter, where captureNativeExceptions defaults to false. error-tracking-upload-source-maps/description.md
• Same for the Nuxt module, where client and server capture are separate opt-in blocks. nuxt.config.ts
• The option name is copied from the wrong SDK, like capture_exceptions on posthog-node, and silently ignored. capture-exceptions.md
• The .NET SDK is assumed to autocapture like Python and Node, but it has no automatic capture yet. commandments.yaml
• Flutter exceptions are captured without a stack trace, and uncaught errors are never captured. The wizard passes stackTrace and turns on the errorTrackingConfig flags. error-tracking-upload-source-maps/description.md

The same error is captured many times, or normal failures and noise are captured as errors.

Example: Extra global error listener beside SDK autocapture

Problem. Enabling autocapture looks too passive, so the agent also registers window.onerror, unhandledrejection, uncaughtException or sys.excepthook handlers the SDK already owns.

Impact. Silent: every uncaught error is sent twice, doubling issue counts and cost, and the copy drifts from SDK behavior.

posthog.init(token, { capture_exceptions: true })
window.addEventListener('error', e => posthog.captureException(e.error))
window.addEventListener('unhandledrejection', e =>
  posthog.captureException(e.reason))

posthog.init(token, { capture_exceptions: true }) // SDK owns the global handlers
// add only what the SDK cannot see: Express error middleware,
// Vue app.config.errorHandler, Angular ErrorHandler,
// SvelteKit handleError, React error boundary, Next.js global-error

Also catches:

• Validation errors, 4xx responses and cancellations are captured as exceptions, which buries real issues. The wizard flags expected failures in its audit.
• Errors are sent as product events with capture(), so stack traces land in analytics. The wizard uses captureException.
• Console error capture is left on, so console noise and browser extension errors are billed. The wizard turns console error capture off. error-tracking.md
• Elixir errors group poorly and have no source in releases. The wizard sets in_app_otp_apps and packages source code before release. commandments.yaml
• Manual captures are added to every route and component, which makes a large diff with partial coverage. The wizard captures once at init and once in the framework's error handler. error-tracking.md
• A hand-built global handler like sys.excepthook or a custom React boundary replaces an SDK init option. error-tracking.md
• One failure is logged, captured and rethrown at each layer, so it becomes several issues. error-tracking-step/description.md

Production stack traces stay unreadable because source maps or debug symbols are missing, never injected, or never uploaded.

Example: Maps uploaded without chunk ID injection

Problem. 'Upload the source maps' reads as one step, but PostHog matches maps to bundles by an injected chunkId comment, which a bare upload never adds.

Impact. Silent: uploaded maps cannot be matched to deployed bundles, so traces stay minified.

"build": "tsc && posthog-cli sourcemap upload --directory ./dist"
// bundles in ./dist have no //# chunkId comment

"build": "tsc && posthog-cli --dotenv-file .env sourcemap process --directory ./dist --release-name my-app"
// process = inject chunk IDs + upload; deploy the injected files

Also catches:

• The deployed bundle is never checked for the injected chunk ID, and the .map files may ship publicly. error-tracking-upload-source-maps/description.md
• A Rust release build has no debug info or is stripped, so uploaded symbols resolve nothing. The wizard sets the release profile to keep line tables. error-tracking-upload-source-maps/description.md
• Same for Go, where the -s -w and -trimpath release flags delete what symbol upload needs. error-tracking-upload-source-maps/description.md
• Same for Go, where a plain go build has no GNU build ID on Linux and compressed DWARF on macOS. error-tracking-upload-source-maps/description.md
• Same for JavaScript, where tsc or the bundler emits no maps, or maps without sourcesContent. error-tracking-upload-source-maps/description.md
• A Go binary is tested without re-uploading its symbols, and each build has its own id. The wizard builds and uploads in one step before running the binary. error-tracking-upload-source-maps/description.md
• Source maps are generated but never uploaded, so production traces stay minified. The wizard wires the upload into the build. prompt.ts
• An already integrated project is treated as done, so source map upload is never checked.
• A web source map recipe is used on mobile apps, which need their own debug symbols. The wizard uses each platform's plugin or symbol upload. error-tracking-upload-source-maps/description.md
• Same for iOS, where a JS-style CLI step misses the Xcode dSYM settings. error-tracking-upload-source-maps/description.md
• Same for Android, where a hand-rolled posthog-cli step replaces the Gradle plugin that hooks minified variants. error-tracking-upload-source-maps/description.md
• Same for Next.js, Nuxt, Angular and React plus Vite, which have dedicated integrations instead of a generic CLI step. error-tracking-upload-source-maps/detect.ts
• Flutter symbols are uploaded for one platform only. The wizard wires one upload path per platform directory. error-tracking-upload-source-maps/description.md
• Same for React Native, where only JS and Hermes maps are wired and native crash capture stays off. error-tracking-upload-source-maps/description.md
• Python, Ruby and PHP apps skip the upload step, and release tagging goes with it. The wizard still wires release linking for these apps. error-tracking-link-releases/description.md
• The source map test runs on the dev server, where upload never runs. The wizard tests on a production build. error-tracking-upload-source-maps/description.md
• Same for mobile, where debug builds skip the Android mapping and iOS dSYM upload. error-tracking-upload-source-maps/description.md

Source map uploads and release linking break in CI and deploys because credentials, names or steps do not line up.

Example: Upload credentials never reach the CI or Docker build

Problem. Agents write POSTHOGCLI* to the local .env and edit the bundler config, but never trace where the production build runs. Env does not cross into a Docker build, composite action or SSH session.

Impact. Deploys build fine, no symbol set uploads, and Error Tracking keeps showing minified stack traces.

- name: Build and push image
  uses: docker/build-push-action@v6
  with:
    context: .
    push: true
# Dockerfile `RUN npm run build` sees no POSTHOG_CLI_* vars

- name: Build and push image
  uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    build-args: |
      POSTHOG_CLI_API_KEY=${{ secrets.POSTHOG_CLI_API_KEY }}
      POSTHOG_CLI_PROJECT_ID=${{ secrets.POSTHOG_CLI_PROJECT_ID }}
# multi-stage: ARG/ENV in the build stage before the build RUN; single-stage: secrets: input + BuildKit secret

Also catches:

• To test release linking, the agent edits local env files and runs posthog-cli, which creates a real release. The wizard changes only the deploy step and never runs posthog-cli. link-releases.md
• posthog-cli is installed globally or with npm in native apps that have no package.json. The wizard installs posthog-cli once before the agent runs. posthog-cli-preinstall.ts
• Upload credential names do not match what the uploader reads, so uploads are skipped. The wizard writes one set of names for the wired uploader. error-tracking-upload-source-maps/description.md
• CI uses a different variable name than the local .env, or swaps the personal key for the project token. error-tracking-upload-source-maps/description.md
• Same for a local composite GitHub action, which only sees inputs, so secrets are silently empty. error-tracking-upload-source-maps/description.md
• Same for git metadata, which a docker build cannot see, so releases link to no commit. error-tracking-upload-source-maps/description.md
• The agent invents a CI workflow it cannot trace to the real deploy. The wizard edits only existing CI files and tells the user what the build needs. prompt.ts
• The public project token is used to upload maps, which needs a personal API key. The wizard asks for a personal key with the right scopes. error-tracking-upload-source-maps/description.md
• The backend release name differs from the source map release, so one deploy makes two releases. The wizard keeps the defaults so both match. error-tracking-link-releases/description.md
• POSTHOG_RELEASE_ID is set in CI or an early Docker stage but never reaches the running container. The wizard sets it in the final stage. link-releases.md
• Same for PHP-FPM, where a repo pool config with clear_env strips the release ID from workers. error-tracking-link-releases/description.md
• Releases are created on every branch and PR build. The wizard adds the resolve step to the production deploy job only. error-tracking-link-releases/description.md
• The release step assumes npm or curl exist, so it fails on slim CI images. The wizard installs what the step needs first. error-tracking-link-releases/description.md

The integration breaks the build, or builds output the app never runs.

Example: Build emits bundle but start runs source

Problem. To get source maps the agent adds a bundling step. It never checks what the start script actually executes, and the mismatch causes no error.

Impact. Silent: uploaded source maps never match the code that runs, so every map goes unused.

"build": "esbuild src/index.ts --bundle --outdir=dist --sourcemap",
"start": "node src/index.js"

"build": "esbuild src/index.ts --bundle --outdir=dist --sourcemap",
"start": "node dist/index.js"

Also catches:

• Source map upload breaks Astro builds, which emit maps with no matching scripts. The wizard skips the uploader for Astro and says so. setup-error-tracking.md
• A webpack devtool setting clashes with the PostHog plugin's own source map plugin. The wizard sets devtool to false. error-tracking-upload-source-maps/description.md
• Init fails strict typecheck on env lookups, so no bundle or maps are built. The wizard narrows the value it passes to init. init.md
• esbuild emits a CommonJS bundle in an ESM package, which crashes at boot. The wizard reads the package type and sets the format. configure.md
• A full production build is never run after the generated code, so CI breaks right after success. The wizard lists a full build in the pre-merge checklist. 4-conclude.md
• React Router v7 SSR is missing ssr.noExternal for the PostHog packages, so server renders fail. The wizard adds them to the Vite config. vite.config.ts
• An Astro PostHog script without is:inline is bundled as a module and breaks. The wizard adds is:inline and passes public env values in. commandments.yaml
• The reverse. With is:inline set, a bare npm import cannot resolve in the browser. astro-static
• A bare use Throwable in Laravel's bootstrap/app.php breaks config:cache. The wizard uses the fully qualified name.

Flags are read in a way that gives the wrong value, costs too much, or breaks the page when evaluation fails.

Example: Flag evaluation failure takes the page down

Problem. evaluateFlags reads like a local lookup, so the agent calls it inline, unwraps the result or pattern-matches only success. It is a network call that throws when PostHog is slow or down.

Impact. A PostHog outage turns the page into a 500, a Rust panic or an Elixir MatchError instead of falling back to the flag being off.

PostHogFeatureFlagEvaluations flags = posthog.evaluateFlags(userId);
model.addAttribute("showNewFeature", flags.isEnabled("new-dashboard-feature"));
// Rust: .await.unwrap()   Elixir: {:ok, snapshot} = evaluate_flags(id)