Skip to content
All guides
Reference 6 min read

Troubleshooting & FAQ

Quick answers to the questions that come up most — launch errors, SmartScreen, empty GSC charts, zero impact scores, skipped rendering, and what the AI does (and never does).

A short, evergreen reference for the things that occasionally trip people up — and the questions buyers ask before they trust the tool. Every answer here is deterministic: Crawl Cove tells you why something is empty or skipped rather than failing silently, so most "issues" are really just a panel waiting for an optional key.

Launch & install

The app shows a backend error screen on launch

This is the app being honest, not broken. On startup Crawl Cove runs a backend self-check; if the local SQLite database can't open, you get a readable error screen instead of a dead blank window.

The usual cause when running from source is that the native SQLite addon was built for the wrong runtime (system-Node instead of Electron's ABI). Run the app with npm run dev — its predev step rebuilds the addon for Electron automatically. If you just ran the unit tests, the addon was rebuilt for system-Node; launching the app again re-rebuilds it for Electron. The dance is automatic.

Windows SmartScreen warns the app is "unrecognized"

The build is currently unsigned, so SmartScreen flags it on first launch. Click More info → Run anyway. Nothing is wrong with the file — code signing is a future addition that needs only a certificate, not a code change.

Search Console & impact

My GSC charts are empty, or sync failed after about a week

You're almost certainly in Google's OAuth Testing mode, where Google expires refresh tokens after 7 days. After a week the next sync fails and you'll see a prominent red "token invalid — reconnect required" banner (failures are never silent).

Two fixes: click Reconnect Google account when the banner appears (~weekly), or publish the OAuth app so tokens stop expiring on the 7-day clock. With only the read-only Search Console scope, publishing needs no Google verification for your own use.

Impact scores are all 0

Impact score is severity weight × log of GSC impressions on the affected URLs. With no Search Console data connected for that client, there are no impressions to weight by, so every score is 0 and findings fall back to ranking by severity instead.

Connect Search Console for the client and findings re-rank by real traffic immediately. See Connecting Google Search Console and Prioritising with impact score.

Rendering, Lighthouse & optional panels

Tier-2 rendering or the Lighthouse lab is skipped

Both the Tier-2 rendered crawl pass and the on-demand Lighthouse lab use a Chromium binary that isn't bundled. Install it once per machine:

npx playwright install chromium

Until then, crawls still complete with Tier-1 (static HTML) data and you'll see an honest badge — "Tier-2 rendering skipped" or "Lighthouse skipped — install chromium." Nothing crashes; you just don't get the rendered pass.

"CrUX API key not set" / "Bing API key not set" / "Open PageRank key not set"

These are optional, gated panels — everything else on the page works without them. Add the relevant key in Settings (each is stored encrypted) and the panel comes to life:

Note

None of these keys are required to crawl, audit, or report. They unlock extra free data sources, not core functionality.

Findings & the AI layer

A finding is wrong or not relevant for this client

Two deterministic options, both honest:

  • Ignore-with-reason the individual finding. This keeps the queue honest by recording why it was ignored rather than letting it silently rot.
  • Disable or retune the check in the Check Registry — enable/disable per client, override the severity, or adjust thresholds (e.g. title length). Your overrides are respected by the audit pipeline on the next crawl. See Tuning checks.

Does any AI invent or remove findings?

No. Every finding comes from a coded, deterministic check with a stable id and version — never from an AI guess. The optional LLM layer only explains findings in plain English and drafts report summaries, and its output is validated against a strict schema. It can never create, remove, or rescore a finding. When you put a number in front of a client, you can stand behind it.

Data & clients

Where is my data? Is it uploaded anywhere?

Everything is local. Your data lives in a SQLite database at <userData>/crawlcove.db, with secrets encrypted separately under <userData>/secrets/. Nothing is uploaded to a SaaS backend — there isn't one. For agencies handling client sites under NDA, "nothing phones home" is a feature you can sell. Full detail in Privacy & where your data lives.

Can I delete a client?

Clients are archived, never deleted, so audit history is always preserved. Archiving hides a client (and its tasks) from active and global views without discarding any of the run-to-run deltas that prove your work.

Tip

Most "something's missing" moments in Crawl Cove are answered by the Connections page for a client — when any chart is empty, it tells you why in one look. Silent integration failure is designed out of the product.

Next

Put this guide into practice

Crawl Cove runs these audits on your machine and tells you exactly what to fix first. See the features or compare the plans.

Download Crawl Cove

Keep reading