Troubleshooting

The most common issues that surface during SDK install.

"The trigger button doesn't appear"

Four causes:

1. BugJar.init() was never called. Your bugjar:ready listener didn't run, or didn't call init(). Verify the listener fires (drop a console.log inside it). If the script tag is missing or the SDK URL is wrong, the event will never fire.

2. The listener was registered AFTER the SDK script tag. Module scripts are deferred, so they execute after HTML parse — but if your addEventListener lives in a deferred script (or in <script type="module">), it might run after the SDK already fired bugjar:ready and miss the event. Always register the listener in a synchronous inline <script> placed BEFORE the SDK <script src=…> tag.

3. projectKey is missing or invalid. Look for [BugJar] init() requires a projectKey… thrown from init(). If you're loading from /sdk/{publicKey}.js the server inlines it automatically — a thrown error here means the URL is wrong or the project was deleted. If you're using npm, pass projectKey in your init({}) call. Keys start with proj_live_... (or proj_test_... for sandbox).

4. ui.showTrigger: false is set. That option intentionally suppresses the built-in pill. Remove it, or call BugJar.open() from your own UI element. (See Customize the trigger.)

"CORS error when submitting a report"

The dashboard's API enforces an allowed_origins list per project. If the SDK is loaded from a domain not on the list, the upload-URL request returns HTTP 422 with errors.origin populated; the browser may surface this as a CORS error.

Add your domain in Settings → Projects → Allowed origins.

"Redaction isn't applying to my custom field"

Verify the field has a data-bugjar-mask or data-bugjar-block attribute on it (or on an ancestor). Without one, the SDK's default patterns are the only thing redacting that field — and they only catch the standard PII shapes (email, card, SSN, JWT, API keys). Industry-specific fields need an explicit annotation.

Per-project regex patterns are on the roadmap (Team tier when shipped). Until then, the annotation-based approach is the recommended path for app-specific masking.

"TypeScript can't find @bugjar/reporter types"

The supported install is the dashboard-served <script src=".../sdk/{key}.js"> tag — npm is no longer the recommended path. If you have a legacy npm install @bugjar/reporter bundling the SDK into your build and TypeScript complains, your tsconfig.json may have skipLibCheck: false plus a strict mode that's tripping on rrweb's types. Add to tsconfig.json:

{
    "compilerOptions": {
        "skipLibCheck": true
    }
}

"I can't reproduce a customer's bug from the replay"

Three things to check:

1. The customer's data-bugjar-block elements — anything they marked as off-limits won't be in the replay. The replay shows masked layout but not content. If the bug requires seeing the original content, you'll need to ask the customer to re-record with the block attribute removed on the relevant element.

2. Browser-extension interference — many ad-blockers and privacy extensions interact with rrweb. The replay may show the page without the extension's effects, even though the customer hit the bug WITH the extension.

3. Source-map mismatch — if the customer hit the bug on a deploy that's since been rolled back, the replay's stack traces won't resolve. Check the page.url field's deploy-id query parameter to identify which deploy was live.