HomeFeaturesPricingDocumentationContactDOWNLOAD

Troubleshooting

Common problems, where SiteCMD's logs and database live, and how to get unstuck.

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 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: 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 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 the connected service, that action needs founder-beta access; use the contact form if your installation has not been invited.

“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 → 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. For an issue you want to file, attach the most recent log file (or its tail). The audit.log in the data directory is the only JSON-line log.

Resetting

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

  1. Quit SiteCMD (from the tray menu or by pressing Cmd/Ctrl+Q in the app).
  2. Move (don’t delete, in case you want it back) the SiteCMD app-data directory to a backup location.
  3. 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 sitecmd.log from the log directory above

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