make error tracking troubleshooting even better (#14171)

* make error tracking troubleshooting great

* title case

* nit

* nits

* Fix typos

* Update contents/docs/error-tracking/common-questions.mdx

Co-authored-by: Vincent (Wen Yu) Ge <[email protected]>

* Update contents/docs/error-tracking/common-questions.mdx

Co-authored-by: Vincent (Wen Yu) Ge <[email protected]>

* Update src/components/Docs/SolvedQuestions/index.tsx

Co-authored-by: Edwin Lim <[email protected]>

* feedback 1

* tweak styling

* add style guide sections

* use os components, replace placeholder text

* Update src/components/AskAIInput/index.tsx

Co-authored-by: Edwin Lim <[email protected]>

---------

Co-authored-by: PostHog <[email protected]>
Co-authored-by: Vincent (Wen Yu) Ge <[email protected]>
Co-authored-by: Edwin Lim <[email protected]>

Author: 4 people

contents/docs/error-tracking/common-questions.mdx

@@ -1,85 +1,133 @@
 ---
-title: Error tracking troubleshooting and FAQs
+title: Error Tracking troubleshooting
 ---
 
-## FAQs
+This page covers troubleshooting for Error Tracking. For setup, see the [installation guides](/docs/error-tracking/installation).
 
-### How much does error tracking cost?
+## Have a question? Ask PostHog AI
 
-Your first 100,000 `$exception` events each month are free – i.e. if you never exceed this number, you can use error tracking for free.
+<AskAIInput placeholder="Type your question and hit enter..." />
 
-After this, we charge a small amount for each `$exception` event you send. The more events you send, the less each event costs.
+## Exceptions not appearing
 
-Go to the [pricing page](/pricing) to use our calculator to get an estimate. You can also view an estimate on [your billing page](https://us.posthog.com/organization/billing).
+If PostHog isn't capturing errors:
 
-### Are web workers supported?
+1. Use the [SDK Doctor](/docs/sdk-doctor) to verify your SDKs are updated to the latest version
+2. Verify **exception capture** is enabled in [project settings](https://app.posthog.com/settings/project-error-tracking#exception-autocapture)
+3. Only unhandled exceptions auto-capture. For caught errors, use `posthog.captureException()`:
 
-Yes. Error tracking will work as long as you initialize PostHog in the [web worker](/tutorials/web-worker). You will need to disable any features that rely on the `window` object:
+    ```js
+    try {
+        // code that errors
+    } catch (error) {
+        posthog.captureException(error)
+    }
+    ```
 
-```js
-posthog.init(token, {
-    ...
-    autocapture: false,
-    capture_pageview: false,
-    capture_pageleave: false,
-    disable_session_recording: true,
-    disable_surveys: true,
-});
-```
+4. Wait a few minutes and check [Error Tracking in the PostHog app](https://app.posthog.com/error_tracking). Issues may take a few minutes to update after ingesting new error events
+
+## Source maps not resolving
+
+If stack traces show minified code instead of original source:
+
+1. Verify source maps are uploaded to the correct project by navigating to [Error Tracking](https://app.posthog.com/error_tracking) and selecting **Configure** > **Symbol sets**. You'll also see warnings for missing symbol sets
+2. The `release` tag in your SDK config must match the version you uploaded:
 
-To `identify` users in web workers you will need to pass the distinct ID. This can be done via an env variable or sending it via `postMessage` from your main application.
+    ```js
+    posthog.init('<ph_project_api_key>', {
+        ...
+        session_recording: {
+            recordCrossOriginIframes: true,
+        },
+        release: 'v1.2.3'
+    })
+    ```
 
-### Can exceptions be sampled / ignored
+3. Source map paths must match your production bundle URLs exactly
+4. Upload source maps *before* deploying code that references them
 
-Returning `null` for a given event in the [`before_send`](/docs/libraries/js/features#amending-or-sampling-events) hook will cause it not to be captured. You may want to:
-- Drop certain types of exceptions
-- Randomly sample a subset of all exceptions 
-- Sample based on the events properties (e.g. URL or user)
+See the [source maps guide](/docs/error-tracking/upload-source-maps/) for upload instructions.
 
-## Troubleshooting
+## 'Script error' with no stack trace
 
-### What is a 'Script error.' with no stack traces?
+For security purposes, browsers hide error details from scripts loaded from different domains. This shows as `Script error` with no stack trace.
 
-For security purposes, errors sent from a JavaScript file served on a different domain hide the original error to avoid unintentionally leaking sensitive information to any `onerror` handler. This is often the case for third party scripts running on a site and results in an obfuscated 'Script error.' with no associated stack trace.
+To fix, add `crossorigin="anonymous"` to your script tags:
 
-To see the actual error, the erroring script needs to be loaded `anonymously` which excludes potentially user-identifying information such as cookies from being transmitted when requesting the file.
+```html
+<script src="https://your-cdn.com/app.js" crossorigin="anonymous"></script>
+```
+
+If the script is within your control, also set the `Access-Control-Allow-Origin` response header to your origin:
 
 ```
-<script src="https://third-party.domain/script.js" crossorigin="anonymous"></script>
+Access-Control-Allow-Origin: https://yourdomain.com
 ```
 
-It can be somewhat difficult to know which script is causing the error because the captured exception provides no context. There is no solution to this other than to work through a process of elimination.
+Or allow any origin:
+
+```
+Access-Control-Allow-Origin: *
+```
 
-If the script is within your control, you also need to set the `Access-Control-Allow-Origin` response header to include the calling domain. This can be a comma separated list of valid domains or a global wildcard e.g `*`.
+You can also use [session recordings](/docs/session-replay) to see what user actions triggered the error.
 
-### What is a 'Non-Error promise rejection' error with no stack traces?
+## 'Non-Error promise rejection' with no stack trace
 
-When you do not pass an `Error` object to a rejected promise, the resulting error captured will be a generic 'Non-Error promise rejection' and the stack trace context will not be included. An example of this is:
+This happens when you reject a promise with a string instead of an `Error` object. Without an `Error` object, there's no stack trace to capture.
 
-```js
+<MultiLanguage>
+
+```js file=Without stack trace
 new Promise((resolve, reject) => {
-    // the captured error will be 'Non-Error promise rejection' without a stack trace
-    reject('Something went wrong');
+  reject('Something went wrong'); // String has no stack trace
 });
-```
 
-The easiest way to resolve this is to always reject promises with an `Error` object:
+Promise.reject('Something went wrong');
+```
 
-```js
+```js file=With stack trace
 new Promise((resolve, reject) => {
-    // the captured error will be 'Something went wrong' with a stack trace
-    reject(new Error('Something went wrong'));
+  reject(new Error('Something went wrong')); // Error includes stack trace
 });
+
+Promise.reject(new Error('Something went wrong'));
+```
+
+</MultiLanguage>
+
+For third-party libraries that reject with strings, wrap the rejection:
+
+```js
+somePromise()
+  .catch(err => {
+    posthog.captureException(new Error(err))
+    throw err
+  })
 ```
 
-### What is a 'Minified React error' with no stack traces?
+## 'Minified React error' with no stack trace
 
-In order to reduce bundle size in production builds React removes useful debugging information from errors thrown by the framework. This results in errors that lack stack traces and look like the following:
+In production builds, React removes debugging information to reduce bundle size. Errors look like:
 
 ```
-Minified React error #123; visit https://reactjs.org/docs/error-decoder.html?invariant=123 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
+Minified React error #123; visit https://reactjs.org/docs/error-decoder.html?invariant=123
 ```
 
-The link provided in the error message can be used to look up the full error message and understand the cause of the error. However, it will not tell you exactly where in your code the error originates from.
+To debug:
+
+1. Upload source maps to get readable stack traces. See the [source maps guide](/docs/error-tracking/upload-source-maps/)
+2. Visit the error URL in the message to understand what went wrong
+3. Watch [session recordings](/docs/session-replay) to see what user actions triggered the error, then reproduce in development
+4. Use a development build which includes full error messages. Only use this for debugging, not production
+
+## Solved community questions
 
-One way to debug these kinds of issues is to watch session recordings to see what user actions lead up to the error occurring. From there you can try to reproduce the error by following the same steps in your development environment, where the full stack trace will be available.
+<SolvedQuestions
+    topicLabel="Error Tracking"
+    pinnedQuestions={[
+        'code-variables-for-external-libraries-for-python',
+        'trouble-setting-up-source-map-in-vite-react',
+        'webpack-turbopack-plugin-getting-sourcemaps-uploaded-to-vercel'
+    ]}
+/>

contents/handbook/content/docs-style-guide.mdx

@@ -217,6 +217,39 @@ Available props:
 
 The component automatically tracks when users open PostHog AI and includes the current page context.
 
+### AskAIInput
+
+The `<AskAIInput>` component provides a text input for users to ask PostHog AI questions directly within documentation pages. Use this to replace traditional FAQ sections in troubleshooting guides and documentation pages where users frequently have questions. The component opens the PostHog AI chat window with the user's question pre-loaded and includes the current page context. Add a clear h2 heading like "Have a question? Ask PostHog AI" above the component.
+
+> **Note:** Customize the `placeholder` prop per page to provide context-specific guidance. The default is `Ask a question...`
+
+```mdx
+## Have a question? Ask PostHog AI
+
+<AskAIInput placeholder="Type your question and hit enter..." />
+```
+
+<AskAIInput placeholder="Type your question and hit enter..." />
+
+> See [src/components/AskAIInput/index.tsx](https://github.com/PostHog/posthog.com/blob/master/src/components/AskAIInput/index.tsx) for all available props.
+
+### SolvedQuestions
+
+The `<SolvedQuestions>` component displays resolved community questions from a specific topic. Use this in troubleshooting guides to highlight common issues and their solutions. Find question slugs by visiting the community question page and copying the URL slug.
+
+> **Note:** Use the `pinnedQuestions` prop to manually curate which questions appear. When provided, the component shows only those questions. If not provided, it shows recent solved posts.
+
+```mdx
+<SolvedQuestions
+    topicLabel="Error Tracking"
+    pinnedQuestions={[
+        'code-variables-for-external-libraries-for-python',
+        'trouble-setting-up-source-map-in-vite-react',
+        'webpack-turbopack-plugin-getting-sourcemaps-uploaded-to-vercel'
+    ]}
+/>
+```
+
 ### Steps
 
 Use the `<Steps>` component for content that walks the reader through a strict sequence of instructions. Think how-to guides or step-by-step tutorials.

src/components/AskAIInput/index.tsx

@@ -0,0 +1,66 @@
+// Use to replace FAQs with an Ask PostHog AI input interface, let users choose their own FAQs. Add a h2 heading "Have a question? Ask PostHog AI" above this component in the MDX file
+
+import React, { useState } from 'react'
+import { IconSparkles } from '@posthog/icons'
+import { useLayoutData } from 'components/Layout/hooks'
+import usePostHog from 'hooks/usePostHog'
+import { useApp } from '../../context/App'
+import { useLocation } from '@reach/router'
+import { useWindow } from '../../context/Window'
+import OSButton from 'components/OSButton'
+
+interface AskAIInputProps {
+    placeholder?: string
+    className?: string
+}
+
+const DEFAULT_PLACEHOLDER = 'Ask a question...'
+
+export default function AskAIInput({ placeholder = DEFAULT_PLACEHOLDER, className = '' }: AskAIInputProps) {
+    const [question, setQuestion] = useState('')
+    const posthog = usePostHog()
+    const { compact } = useLayoutData()
+    const { openNewChat } = useApp()
+    const { appWindow } = useWindow()
+    const location = useLocation()
+
+    const handleSubmit = () => {
+        if (!question.trim()) return
+        posthog?.capture('Opened MaxAI chat', { source: 'AskAI input' })
+        openNewChat({
+            path: `ask-max-${location.pathname}`,
+            initialQuestion: question,
+            context: [
+                {
+                    type: 'page',
+                    value: {
+                        path: appWindow?.path || '',
+                        label: appWindow?.meta?.title || '',
+                    },
+                },
+            ],
+        })
+    }
+
+    if (compact) return null
+
+    return (
+        <div className={`flex gap-2 items-center ${className}`}>
+            <input
+                type="text"
+                value={question}
+                onChange={(e: React.ChangeEvent<HTMLInputElement>) => setQuestion(e.target.value)}
+                onKeyDown={(e: React.KeyboardEvent<HTMLInputElement>) => {
+                    if (e.key === 'Enter') {
+                        handleSubmit()
+                    }
+                }}
+                placeholder={placeholder}
+                className="flex-1 bg-primary border border-primary rounded px-2.5 py-2.5 text-[15px] ring-0 focus:ring-0"
+            />
+            <OSButton variant="secondary" size="md" onClick={handleSubmit} icon={<IconSparkles />} iconPosition="right">
+                Ask PostHog AI
+            </OSButton>
+        </div>
+    )
+}

src/components/CodeBlock/index.tsx

@@ -388,7 +388,7 @@ export const CodeBlock = ({
                                                 href={`${generateSQLEditorLink(activeLanguage.code)}`}
                                                 target="_blank"
                                                 rel="noopener noreferrer"
-                                                className="inline-flex items-center gap-1 whitespace-nowrap text-primary/50 hover:text-primary/75 dark:text-primary-dark/50 dark:hover:text-primary-dark/75 px-1 py-1 hover:bg-light dark:hover:bg-dark border border-transparent hover:border-light dark:hover:border-dark rounded relative hover:scale-[1.02] active:top-[.5px] active:scale-[.99]"
+                                                className="inline-flex items-center gap-1 whitespace-nowrap text-muted hover:text-secondary px-1 py-1 bg-transparent hover:bg-border border border-transparent hover:border rounded relative hover:scale-[1.02] active:top-[.5px] active:scale-[.99]"
                                             >
                                                 Run in PostHog
                                                 <IconArrowUpRight className="w-4 h-4" />
@@ -402,7 +402,7 @@ export const CodeBlock = ({
                                                 onClick={() =>
                                                     handleAskAboutCode(activeLanguage.code, activeLanguage.language)
                                                 }
-                                                className="ask-posthog-ai-code-snippet inline-flex items-center gap-1 text-primary/50 hover:text-primary/75 dark:text-primary-dark/50 dark:hover:text-primary-dark/75 px-1 py-1 hover:bg-light dark:hover:bg-dark border border-transparent hover:border-light dark:hover:border-dark rounded relative hover:scale-[1.02] active:top-[.5px] active:scale-[.99]"
+                                                className="ask-posthog-ai-code-snippet inline-flex items-center gap-1 text-muted hover:text-secondary px-1 py-1 bg-transparent hover:bg-border border border-transparent hover:border rounded relative hover:scale-[1.02] active:top-[.5px] active:scale-[.99]"
                                             >
                                                 <span className="hidden group-hover/askai:inline whitespace-nowrap text-sm">
                                                     PostHog AI
@@ -416,7 +416,7 @@ export const CodeBlock = ({
                                         <div className="relative flex items-center justify-center px-1">
                                             <button
                                                 onClick={() => copyToClipboard(activeLanguage.code)}
-                                                className="text-muted hover:text-secondary px-1 py-1 hover:bg-light dark:hover:bg-dark border border-transparent hover:border rounded relative hover:scale-[1.02] active:top-[.5px] active:scale-[.99]"
+                                                className="text-muted hover:text-secondary px-1 py-1 bg-transparent hover:bg-border border border-transparent hover:border rounded relative hover:scale-[1.02] active:top-[.5px] active:scale-[.99]"
                                                 title="Copy to clipboard"
                                             >
                                                 <svg