The short version: most issues fall into a few categories. This page covers the common ones, and points at the logs and data locations when you need to dig deeper.

Common scan problems

”Scan failed: connection refused”

SiteCMD couldn’t reach the URL. Check:

The URL is correct and reachable from your machine (try it in a browser)
The site isn’t requiring authentication SiteCMD doesn’t have (HTTP basic auth, IP allowlist)
For local dev URLs (localhost:3000), the dev server is actually running

If the URL is reachable in a browser but not from SiteCMD, it’s likely a network policy issue. SiteCMD blocks scans against private RFC1918 IP ranges (10.x, 192.168.x, etc.) by default, even if those resolve from a domain. Localhost is allowed; an internal LAN IP isn’t.

”Scan failed: timeout”

The scan didn’t finish within the configured timeout (default 30 seconds per request). Most often this is because:

A probe target is slow or unresponsive (e.g. /robots.txt returning a 500 after 60s)
The site itself is slow to respond on first request
You’re scanning over a slow network

Raise the timeout in Settings → Scan preferences (max 60 seconds). If a specific probe is consistently the slowest, consider whether that endpoint is actually broken on your site.

”Code Scan could not find app source files”

The folder you linked doesn’t look like a project root to SiteCMD. The audit needs at least one of these markers in the linked folder:

package.json
src/
app/
pages/
functions/
schema/
config/

If your project lives in a subdirectory of a monorepo, link the subdirectory directly, not the monorepo root. SiteCMD doesn’t auto-detect which subdirectory is your project.

”Some checks were skipped”

Some checks are skipped on purpose, depending on the scan type:

Pre-deploy scans skip checks that need a running site, like uptime probes.
Focused category scans (security, accessibility, polish) skip everything outside the focused category. Use a full scan to see them.
Anonymous scans skip checks that require integration data.

The list of skipped checks appears at the bottom of the scan summary, with the reason each was skipped.

Integration problems

”Integration token rejected”

The API key or OAuth token SiteCMD has for this integration was rejected by the service. Most common causes:

The token was revoked on the service’s side
The token’s scopes changed
The token expired (OAuth tokens for some services have refresh requirements)

Fix: Settings → Integrations → [the service] → Disconnect, then reconnect. SiteCMD will walk you through the auth flow again.

”GitHub: no deploys found”

If your repo uses GitHub Actions for deploys but they’re not showing up:

Confirm SiteCMD has the repo scope (deploys are gated by repo permissions)
Make sure you’re using actions/deploy-pages or another action that creates GitHub Deployment objects, not just running an arbitrary deploy command
The deploys API only returns recent deploys. If your last deploy was months ago, you may need to push something newer to see signal

”Search Console: no data”

Search Console takes a few days after property verification to start showing data, and the API only returns data once it’s processed. If you connected SiteCMD the day you verified the property, give it 48 hours and try again.

If the property is verified and has data in the Search Console web UI but not in SiteCMD, check that:

The OAuth account you connected has access to this property
The property type matches the URL you’re scanning (sc-domain: properties cover all subdomains; URL-prefix properties don’t)

License and tier problems

”Premium feature: this requires Core”

You’re on the Free tier and tried to use a Core feature (cross-source correlation, fix guides, ticket mirroring, etc.). Options:

Upgrade to Core via the in-app billing flow
Use the free alternative (the feature usually has a free read-only equivalent)

“License validation failed”

SiteCMD couldn’t reach the license server. If you’re online and this persists, check that api.lemonsqueezy.com isn’t being blocked by your firewall, VPN, or DNS filter.

SiteCMD enters an offline grace period when it can’t validate the license, during which premium features keep working. If you’re past the grace period, premium features will pause until the next successful validation. Reconnect to the internet and reopen the app to retry.

App and data problems

Where the database lives

The local SQLite database, scan history, audit log, and other persistent files live in SiteCMD’s app-data directory, in a subdirectory named com.sitecmd.app:

macOS: ~/Library/Application Support/com.sitecmd.app/
Windows: %LOCALAPPDATA%\com.sitecmd.app\ (falls back to %APPDATA% if LOCALAPPDATA is unset)
Linux: $XDG_DATA_HOME/com.sitecmd.app/ (defaults to ~/.local/share/com.sitecmd.app/)

Inside that directory you’ll find:

sitecmd.db (and sitecmd.db-wal, sitecmd.db-shm) — the SQLite database
audit.log — JSONL log of sensitive operations
logs/ — application log files

Reading the logs

If something’s clearly broken and the in-app error isn’t enough, the application logs are the next place to look. logs/ contains rolling log files; the most recent is the active one. Tauri’s tracing output goes here.

For an open issue you want to file, attach the most recent log file (or its tail). The logs are JSON-line formatted and easy to share.

Resetting

If your local data has become inconsistent and you want a clean start:

Quit SiteCMD (from the tray menu or by pressing Cmd/Ctrl+Q in the app).
Move (don’t delete, in case you want it back) the SiteCMD app-data directory to a backup location.
Relaunch SiteCMD. A fresh database is created on launch.

Note that integration credentials live in your OS keychain, not the app-data directory. Resetting the database doesn’t remove keychain entries. If you want a fully clean slate, also remove “SiteCMD” entries from your OS credential store.

When to file an issue

If you’ve tried the relevant items above and the problem persists, file an issue. Include:

What you were trying to do
What happened (the actual error message, not a paraphrase)
Your platform (macOS / Windows / Linux) and version
The tail of the most recent log file from the logs/ directory

The SiteCMD repository is the right place to file issues. Contact information is on the Contact page.