Diagnoses for the problems that actually come up, roughly in order of frequency.
The widget doesn't appear
Check the script loaded. Open the Network tab and look for latest.js. A failed request means a blocked URL or a typo in the src.
Check auto-init is triggered. With a script tag, data-api-key must be present — auto-init keys off that attribute. Without it, nothing happens until you call Bugdump.init() yourself.
Check for an earlier JavaScript error. If your app throws before init() runs, the widget never initializes. The console will show it.
"Bugdump is not defined". An inline script called Bugdump.init() before the async SDK had finished loading. Add the three-line queue stub before the SDK tag and call bugdump('init', {...}) instead — calls made before the SDK arrives are queued and replayed once it loads, so there is no race. See Choosing an installation method for the stub.
Check hideButton. If it is true, there is no floating button by design — you must call bugdump.open() from your own trigger.
Check an ad blocker. Some blocklists catch third-party widget scripts. Test in a clean profile.
Reports fail to submit
Wrong key. An MCP token (it starts with bdm_) cannot submit reports. The widget needs a widget key, which starts with bd_ and is listed on the project's Widget page. This is the most common cause.
Revoked or mistyped key. Compare it with the keys listed on the project's Widget page.
Monthly report limit reached. Free allows 500 widget reports a month per project, Pro 10,000 and Ultra 100,000. At the limit the panel shows "This site is not accepting feedback right now. Please try again later." with Send disabled, and the API answers 403 with REPORT_QUOTA_EXCEEDED. The count resets at 00:00 UTC on the 1st; the project's Settings page shows it and the reset date.
Task limit reached. A Free project holds up to 10,000 tasks. At that point the widget refuses reports the same way, with 403 TASK_LIMIT_REACHED, and the project's Settings page shows a notice. Paid plans have no task limit.
Rate limit. 10 per minute on Free, 20 on Pro, 60 on Ultra, plus a per-IP limit. A burst from one source can trip this.
Empty description. A description is required — submitting without one shows a validation message rather than sending.
The browser console shows the specific error the SDK logged, which will usually distinguish these immediately.
Screenshots or session replay fail on a self-hosted copy
A 404 on bugdump-html2canvas.js or bugdump-replay.js. The SDK loads its two heavy capture libraries as separate files, fetched only when they are needed. If you self-host or proxy the SDK and copied only latest.js, the entry loads fine and the widget looks healthy — but screenshots and session replay break the moment someone tries to use them.
Copy all three files into the same directory. The entry resolves its chunks relative to its own URL, so they must sit beside it. You may rename the entry; the chunk filenames must stay exactly as they are.
A CSP violation on the chunk request. A strict script-src needs the SDK's origin listed for the chunk fetches, not only for the entry script.
Both failures are visible in the Network tab the first time a user clicks Screenshot or Record. See Widget configuration reference for the full loading model.
Screenshots are blank or wrong
Canvas or video appears empty with screenshotMethod: 'dom'. DOM rendering cannot capture canvas content, cross-origin iframes, or some CSS effects. Switch that route to screen-capture.
A permission dialog appears with screen-capture. That is expected — it is the browser asking. Denying it falls back to DOM capture automatically, which is also when the html2canvas chunk is fetched.
A brief pause before the first screenshot. The screenshot library is downloaded on first use rather than on page load. It is cached for the rest of the session, so only the first capture waits.
Screenshots are missing entirely. Confirm features.screenshot is not false.
Console or network logs are empty
A filter is too aggressive. If you set consoleFilter.levels or networkFilter.includeUrls, you may be excluding everything. Remove the filter temporarily to confirm.
Network bodies are missing. captureNetworkBodies is false by default. Status and timing are still captured — bodies are opt-in.
Reading through MCP. get_report returns a summary: the last 50 console entries with bodies stripped. Use get_report_telemetry for the complete history. A summary showing nothing is not evidence that there is nothing.
Session replay is empty
It is switched off in your config. Check features.sessionReplay and data-session-replay.
The chunk failed to load. On a self-hosted copy, see the section above.
Errors aren't showing up on the Errors page
Capture is off for the project. An owner or admin can turn off Capture JavaScript errors automatically in the project's settings. The project then refuses every error event, captureException included, and the Errors page says capture is off.
Capture is off in your config. Look for captureErrors: false in Bugdump.init(), or data-capture-errors="false" on the script tag.
An older SDK. With npm, error capture needs @bugdump/sdk 0.0.44 or later. The script tag from latest.js has it already.
The monthly error limit is used up. 1,000 error events on Free, 50,000 on Pro, 500,000 on Ultra, counted separately from widget reports. Once the project refuses an event, the widget stops sending errors from that page.
Cross-origin scripts. An error from a script on another origin reaches the page as Script error. with no file and no line, and is never sent. Load that script with crossorigin="anonymous" and serve it with CORS headers to see its errors.
Browser extensions. Errors from extensions are never sent, and neither are ResizeObserver loop warnings.
The error was already sent from this tab. Each distinct error is sent once per browser tab session, so triggering it again in the same tab sends nothing new.
Sampling. With sampleRate below 1, only that share of automatically captured errors is sent, decided once per error.
An ignore rule. Anything matching ignoreErrors is dropped in the browser. The patterns are matched against Type: message, such as TypeError: Load failed.
See Capturing JavaScript errors automatically for the options and limits.
Stack traces are still minified
Upload your build's source maps with @bugdump/cli. If you did and frames still show minified code, the usual cause is deploying files from before sourcemaps inject. See the troubleshooting section of Readable stack traces: uploading source maps.
Integrations stopped working
Credentials expired. Bot tokens get revoked and webhook URLs get rotated. Reconnecting usually fixes it.
The project's owner is on Free. Every integration needs Pro or Ultra. After a downgrade, or while a subscription is paused, integrations stop delivering and show as Paused; they resume when the owner upgrades, and the owner can disconnect them meanwhile.
The monthly report limit is reached. At the limit the widget refuses new reports, so no integration runs until the count resets on the 1st — integrations going quiet can be a symptom of a full month rather than a broken connection.
Webhooks aren't delivered
Plan. Webhooks require Pro or Ultra.
Unreachable URL. localhost is not reachable from our servers. Use a tunneling tool during development.
Endpoint failing or timing out. Respond quickly with a success status, then do slow work asynchronously.
Duplicates arriving. Expected on retry. Make your handler idempotent.
MCP won't connect
MCP_PERSONAL_TOKEN_REQUIRED (401). The client is sending a key that starts with bd_ — a widget key, or one of the shared project MCP keys that existed before personal tokens. Shared keys no longer work. Create your own token on the project's MCP server page (it starts with bdm_) and put it in your client's configuration.
MCP_TOKEN_INVALID (401). The token was revoked, mistyped, or belongs to someone who is no longer a member of the project. Create a new one. A token whose project has been suspended is rejected with this error too.
RATE_LIMIT_EXCEEDED (429). MCP clients can make 300 requests a minute per person, counted across all of that person's tokens and connected apps. An agent stuck in a loop hits this; it clears within a minute.
A sign-in connection asks for a project. It reaches every project you are a member of, so each tool takes a project argument: the project's slug. You can leave it out only if you belong to exactly one project. Otherwise the call fails with MCP_PROJECT_REQUIRED, or MCP_PROJECT_NOT_FOUND for a slug that isn't one of yours; both list your projects, and so does the list_projects tool. MCP_NO_PROJECTS means the account is not a member of any project yet.
The app won't let you sign in. Only Claude, Claude Code, ChatGPT and VS Code can connect by signing in; Cursor, other clients, scripts and CI need a personal token. Guest accounts can't connect — create an account first. See Connecting Claude, ChatGPT or VS Code to BugDump.
A connected app stopped working. It was disconnected under account settings → Security → Connected apps, or your password was reset or changed, which disconnects every app. Connect it again.
The write tools are missing. The token was created without Allow changes, so it is read-only. Create a new token with the box checked — the permission cannot be changed on an existing token. On a sign-in connection you chose Read only: disconnect the app and connect again with Read and write.
Tools missing after an update. MCP tool lists are negotiated at connection time. If the server was updated, reconnect — restart your client or reconnect the server — or you will keep seeing the old tool list.
"Not found" for an ID. IDs must come from a previous response. Task refs (BD-42, #42 or 42) work directly with every task tool, but report IDs must come from list_reports_for_task. A ref carrying another project's key is reported as not found, because a token only ever sees its own project. On a sign-in connection, pass that project's slug as project.
Older reports are gone
Reports are deleted once they are older than the plan's retention period: 30 days on Free, 90 on Pro, 365 on Ultra. Their screenshots, recordings, session replays and console and network data go with them. The task stays, with its comments, activity and properties. After a downgrade or a paused subscription, reports older than the new period are deleted within a day.
Uploads fail
Storage limit. 1 GB on Free, 10 GB on Pro, 50 GB on Ultra.
File too large. 25 MB per file on Free, 250 MB on Pro, 500 MB on Ultra. Screen recordings are the usual culprit — screenRecordingMethod: 'dom' produces much smaller artifacts.
Two widgets appear
init() ran twice. In React Strict Mode, effects run twice in development — call destroy() in your cleanup function.
The widget is in the wrong language
The page's language wins. With the default locale: 'auto', the widget follows <html lang> before the visitor's browser. A page that declares lang="en" gets an English widget for everyone.
A template default. Many starter templates ship <html lang="en"> whatever language the page is actually written in. If your site is in Spanish and the widget is in English, check that attribute first, or set locale (data-locale on the script tag) explicitly.
The language isn't one we ship. The widget ships in English, Russian, Spanish, French, Portuguese and German. Anything else falls back to English; supply your own strings with translations.
An earlier init won. With data-api-key on the script tag, auto-init runs first and a later init({ locale }) is ignored. Put data-locale on the tag instead.
To see what the widget picked, run Bugdump.getInstance()?.getConfig()?.locale in the browser console.
Invitations aren't received
Check spam. Then resend from the members page.
Member limit reached. 3 on Free, 10 on Pro, 100 on Ultra.
Wrong address. Revoke the pending invitation and reissue it.
Still stuck
Two ways to reach us:
File a report through the widget on our own site. We get the console log with it, which is the fastest route to a diagnosis.
Email admin@bugdump.com. Best for account, billing, and anything you would rather not put in a public report.
Either way, include your project slug and — if the problem is in the browser — whatever the console printed.
See also
Contacting support
Plans, limits, and usage
Managing API keys safely