Skip to content
Reference 6 min read

Troubleshooting & FAQ

Quick answers to the questions that come up most: launch errors, SmartScreen, empty GSC charts, zero impact scores, 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"

It should not, from version 1.0.0 onwards: that installer is code-signed with a Microsoft-verified certificate issued to Crawl Cove, so Windows names the publisher. If you are seeing the warning, you are almost certainly running an installer downloaded before 1.0.0, which was genuinely unsigned. Take a fresh copy from your dashboard rather than clicking through the prompt.

macOS refuses to open the app, or warns about the developer

It should not, and if it does something is wrong with the download rather than with the app. The macOS build is signed with an Apple Developer ID certificate and notarised by Apple, so it does not produce the "cannot be opened because the developer cannot be verified" block that unsigned apps do. A single confirmation that you meant to open an application downloaded from the internet is normal; click Open. If you see anything stronger than that, re-download the .dmg from your dashboard, and check you took the one matching your processor (arm64 for Apple Silicon, x64 for Intel). Full walkthrough: Installing Crawl Cove on macOS.

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 is skipped

Since version 1.0.0 the Tier-2 rendered crawl pass drives a Chromium-family browser that is already on the machine: the Playwright chromium if you have one, otherwise Google Chrome, otherwise Microsoft Edge. Edge ships with Windows, so on Windows this usually needs no install at all. On macOS, install Chrome or Edge if you have neither.

With none of the three, crawls still complete with Tier-1 (static HTML) data and you'll see an honest badge: "Tier-2 rendering skipped — Install Google Chrome or Microsoft Edge to enable rendered analysis." Nothing crashes; you just don't get the rendered pass.

A system Chrome or Edge is not the chromium build Crawl Cove pins, so rendered output can vary slightly between browser versions.

The Lighthouse lab is skipped

Since version 1.0.0 the lab and the optional rendered pass resolve a browser the same way, so whatever satisfies one satisfies the other. For the lab that usually means no install at all. It drives whichever browser of that family is already on the machine: the Playwright chromium if you happen to have one, otherwise Google Chrome, otherwise Microsoft Edge. With none of them the panel reads "Lighthouse skipped — no supported browser found" and asks you to install Chrome or Edge and run the check again. CrUX field data is unaffected either way.

"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. Try the SEO Crawler or compare the plans.

Download Crawl Cove

Keep reading