Backstop docs
docs

Troubleshooting

The parent app says my device is offline

  • Wait five minutes. Heartbeats are once per minute; the offline check needs a few misses in a row.
  • Confirm the device is on and awake. Sleep, hibernate, and shutdown all stop the endpoint.
  • Confirm network reachability. From the device, browse to backstop.io. If that fails, it’s a general network problem, not Backstop.

If it’s still offline, capture a diagnostic bundle (see below) and email support@backstop.family.

I’m not getting any alerts

Order of suspicion, cheapest first:

  1. BYOK key exhausted or rate-limited. Check your LLM provider dashboard. The parent app also shows a banner if calls are failing.
  2. Screen recording permission not granted (macOS). System Settings → Privacy & Security → Screen Recording → Backstop should be on. If it isn’t, the endpoint captures a blank canvas.
  3. Cadence too slow. Default is once per 10 minutes; a kid who briefly opens something on a slow cycle won’t be caught.
  4. Taxonomy too narrow. Test your taxonomy in the parent app’s Taxonomy tester with a sample.
  5. Cost cap hit. Check Settings → LLM provider → Spend in the parent app.

Alerts keep firing on things I don’t care about

  • Tighten your taxonomy: add examples_negative entries that resemble the false positives.
  • Consider moving noisy categories from severity 1 to 0 so they land in your digest rather than pinging you.
  • Rebuild in the taxonomy tester before publishing.

The install failed

  • Admin credentials weren’t accepted. You need admin on the device. Backstop cannot install with only standard-user credentials.
  • Antivirus flagged the installer. Add an exclusion for the MSI/PKG. Backstop is signed (EV on Windows, notarized on macOS), so any warning should be dismissible.
  • Pairing code expired. Codes are single-use and expire in 15 minutes. Generate a fresh one in the parent web app.

Chrome or Edge is ignoring the blocklist

  • Backstop uses managed policies. In Chrome, go to chrome://policy and confirm URLBlocklist is listed with a source of “Platform” (Windows) or “MDM” (macOS).
  • If the policy isn’t showing up, restart the browser. Chrome loads managed policies at start-up.
  • The hosts-based fallback catches DNS-level lookups even if the browser policy is bypassed.

The endpoint is using too much CPU or battery

  • The default cadence (10 minutes) should be near-imperceptible. If it isn’t, capture a diagnostic bundle.
  • On macOS you can watch Activity Monitor → Energy — look for backstop-core and backstop-helper.
  • On Windows, use Task Manager → Details → backstop-core.exe.

Diagnostic bundle

The endpoint can generate a redacted diagnostic bundle:

  • Windows: "C:\Program Files\Backstop\backstop-core.exe" diagnostics --out %USERPROFILE%\Desktop\backstop-diag.zip
  • macOS: sudo /Library/Application\ Support/Backstop/backstop-core diagnostics --out ~/Desktop/backstop-diag.zip

The bundle contains logs and configuration hashes but no alert content, no screenshots, and no API keys. Email it to support@backstop.family.