← …

Troubleshooting

Eight things that go wrong, what they mean, and how to fix them. If you're still stuck after any of these, email hello@rootcase.io with a screenshot — we answer fast during the design-partner period.

1. The panel doesn't appear

Symptom: Salesforce shows an error, nothing pops up.

Causes & fixes, in order of likelihood:

  1. No extension key — the extension shows Add your extension key in Settings to create tickets. Open the extension options and paste a key from Settings → Extension Keys (quickstart step 5).
  2. Org not connected yet — connect it in onboarding or Settings.
  3. Not a Lightning page — the extension works on Lightning Experience pages (*.lightning.force.com). Salesforce Classic isn't supported.
For your IT team

The content script only runs on *.lightning.force.com, *.my.salesforce.com, and *.salesforce-setup.com. If your company proxies or rewrites those domains, the extension never mounts. Check the page console for the mount log line.

2. “Can't reach diagnosis service”

Symptom: the panel opens but says it can't reach the diagnosis service.

Cause: the extension can't reach our API — network, VPN, or an outage on our side.

Fix: you can still create a ticket (the panel says so — the error context is preserved). Check your network, then retry.

3. Salesforce connection shows “reconnect needed”

Symptom: a banner in the app says the Salesforce connection needs attention; new errors stop getting diagnosed with fresh metadata.

Cause: your org revoked or expired the OAuth grant — password reset for the connected user, an admin revoked the connected app, or org policy expired the refresh token.

Fix: Settings → Salesforce → Reconnect and approve again. Your synced data and history are intact; reconnecting resumes where things left off.

For your IT team

Code: ORG_AUTH_REVOKED. The refresh attempt got an invalid-grant response, so the connection was flipped to revoked and every affected surface shows the reconnect banner. No data was lost.

4. Ticket creation fails with a connection problem

Symptom: Create ticket fails and the panel says the destination needs to be reconnected.

Cause: the Jira/Linear/Salesforce Case connection lost its authorization — revoked in the other tool, or (for Cases) the Create-on-Case permission was removed.

Fix: an admin reconnects in Settings → Integrations (or re-grants the Case permission — see the Cases guide), then hit Retry on the ticket.

For your IT team

Code: DESTINATION_AUTH. Per-destination reconnect; the ticket stays in a retryable failed state, nothing is lost.

5. “Couldn't diagnose this one”

Symptom: the panel opens but says it couldn't diagnose the error.

Cause: honesty, not breakage — the error didn't match anything in your org's configuration with enough confidence. Custom Apex messages and free-text integration errors are the usual suspects.

Fix: nothing to fix. The ticket you create still carries the full error text, the steps, and the screenshot — a developer gets everything they need. When we're only mostly sure, the panel says Best match — not certain instead of guessing silently.

6. “Screenshot unavailable”

Symptom: the ticket form shows Screenshot unavailable under What's included.

Cause: the browser blocked capture (some managed-Chrome policies), or the image exceeded size limits even after downscaling.

Fix: the ticket is still created with everything else. If your whole team sees this, it's usually a Chrome enterprise policy — worth one question to IT. We never attach an unmasked image as a fallback.

7. Things slow down or ask you to wait

Symptom: a “try again in a moment” style message when diagnosing or creating tickets in rapid bursts.

Cause: rate limits — ours, or your Salesforce org's API allowance. Both protect your org; heavy bursts (a demo loop, a load test) hit them.

Fix: wait a minute and retry. If a real team hits this in normal use, tell us — that's sizing feedback we want.

For your IT team

Code: RATE_LIMITED (HTTP 429) with a retry-after. Salesforce-side, the sync scheduler backs off automatically when your org's daily API consumption runs high; it never exhausts your allowance.

8. Sync looks stuck or partial

Symptom: the dashboard shows a sync still running for a long time, or a component you expect isn't found yet.

Cause: very large orgs (tens of thousands of metadata components) take a while on first sync; subsequent syncs are incremental and fast. A sync can also wait if your org's API budget is temporarily tight (see #7).

Fix: let the first sync finish — the dashboard shows progress and completion. If a specific component is missing after a completed sync, use Sync now in Settings, then contact us if it's still absent.

Extension update notice

If the panel shows A new version of the extension is available — please update, Chrome will usually update on its own within a day. To force it: chrome://extensions → Update. Tickets keep working during the overlap window; the notice exists so old versions never linger for weeks.

Still stuck? hello@rootcase.io — include what you clicked, what you expected, and a screenshot if you can.

Was this helpful?