Troubleshooting - SiteCMD Docs

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, check the address you named. SiteCMD runs on your machine with your network, so a target you can already reach is one it can scan: localhost, a .test hostname, a dev server on your LAN such as http://192.168.1.40:8080/, a container by its service name in CI, or a machine on a tailnet. Refused everywhere: link-local addresses (169.254.x, fe80::) and cloud metadata hostnames, because cloud metadata services answer there, and any scheme other than http:// or https://. A hostname earns private reach only when every address it resolves to is private; a name that also answers publicly is treated as a public site. On a private-network target the hidden browser does not run, so Core Web Vitals and accessibility analysis report as unavailable while every other check runs.

"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 Per-check timeout under Settings → Scanning → Scan Behavior (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 recognizable marker in the linked folder:

A project manifest: package.json, composer.json, Cargo.toml, go.mod, pyproject.toml, requirements.txt, or Gemfile
A framework or schema config: a Next.js, Vite, Astro, or Drizzle config file, or schema.prisma
A source layout: src/, app/, pages/, components/, lib/, api/, functions/, prisma/, migrations/, supabase/, db/, or WordPress/Drupal content directories

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.
Checks that need a connected integration are skipped when that integration isn't connected: analytics, search, and uptime checks need their data source linked first.

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: 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 connected-access problems

"This SiteCMD feature requires a paid plan"

Current releases do not gate local features by plan. Cross-source correlation, fix guides, full MCP detail, browser analysis, reports, and exports are part of the complete free local workbench.

If this message appears for a local action, update SiteCMD to the current release. If it appears while configuring SiteCMD Connect, that action needs beta access; use the contact form to request it.

"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 cannot validate an existing license. Connected-service and maintained-catalog credentials may pause after that grace period until validation succeeds. Local scans, full issue detail, fix guidance, MCP, reports, and exports remain available. Reconnect to the internet and use Settings → Account & Billing → Refresh License 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

Reading the logs

If something's clearly broken and the in-app error isn't enough, the application log is the next place to look. It lives in your OS's per-app log directory, under the app's bundle identifier com.sitecmd.desktop (a different tree from the data directory above):

macOS: ~/Library/Logs/com.sitecmd.desktop/
Windows: %LOCALAPPDATA%\com.sitecmd.desktop\logs\
Linux: $XDG_DATA_HOME/com.sitecmd.desktop/logs/ (defaults to ~/.local/share/com.sitecmd.desktop/logs/)

The active file is sitecmd.log, plain text, rotated at 5 MB with the three most recent old files kept alongside it. Settings → Privacy & Diagnostics → Diagnostic logs → Copy Logs copies a diagnostic snapshot for troubleshooting. Review it before sharing. The audit.log in the data directory is the JSON-line audit trail.

Resetting

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

Choose Quit from SiteCMD's tray menu. Closing the window only hides it.
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.

Desktop integration credentials live in your OS keychain, not the app-data directory. Resetting the database doesn't remove keychain entries or connected-service state. For a clean local reset, also remove "SiteCMD" entries from your OS credential store. Use Settings → Connected → Erase Site Data separately if you also want to erase a connected site's remote state.

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 sitecmd.log from the log directory above

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