Account

Troubleshooting

Common problems, what causes them, and how to fix them. Check the relevant section below before reaching out to support.

GA4 problems

“No GA4 properties found”

The property picker calls GET /properties/ga4, which calls the GA4 Admin API and returns every property your Google account can see. If the list is empty, one of these is true:

  • You connected the wrong Google account — the account you OAuth'd with doesn't have Viewer access on any GA4 property. Sign out of SignalGuide and sign back in with the correct account.
  • Your Google account hasn't been granted access to the property. Have a GA4 admin add your account as a Viewer in GA4 Admin → Account Access Management, then reload the onboarding flow.
  • The GA4 Admin API takes a few minutes to reflect new permission grants. Wait and reload.

Analysis returns empty data from GA4

If analysis runs but the dashboard shows zero views and sessions, the engine likely hit an expired or revoked Google token. The guard in api/services/analysis.py raises EmptyAnalysisError when every configured source returns nothing — it will not overwrite a valid previous snapshot with an empty one.

Fix: go to /login, sign in with Google again. This issues a fresh access and refresh token. Then re-run analysis from the dashboard.

Search Console problems

“No GSC sites found” or site missing from picker

GET /properties/gsc calls searchconsole.sites().list() and returns sites where your Google account is a verified owner or user. A site won't appear if:

  • The site isn't verified in Search Console under the account you connected. Verify at search.google.com/search-console and try again.
  • You connected the wrong Google account. The GSC site is verified under a different Google identity than the one you signed in with.

Low GSC data — fewer impressions than expected

If impressions look lower than what you see in the Search Console UI, check whether you're using a Domain property or a URL-prefix property. A URL-prefix property (e.g. https://example.com/) only covers that exact origin — if your site has traffic on www.example.com or http:// variants, those are counted separately. A Domain property (shown as sc-domain:example.com) covers all subdomains and protocols.

SignalGuide pulls up to 500 pages and 5,000 query×page rows per analysis (see api/services/gsc.py). For sites with more than 500 indexed pages, only the top pages by impressions are included.

Token refresh failures

SignalGuide refreshes your Google access token automatically using the stored refresh token (refresh_access_token in api/services/google_auth.py). If the refresh fails, the server logs “Token refresh failed for user <id>” and data pulls return empty.

Common causes of refresh failure:

  • You revoked SignalGuide's access at myaccount.google.com/permissions.
  • Google revoked the grant — this can happen if your Google account password changed or if the OAuth session is older than 6 months with no activity.
  • You changed the Google account's recovery options or security settings in a way that Google treats as suspicious and revokes outstanding tokens.

Fix in all cases: sign out of SignalGuide and sign back in with Google. The new sign-in issues a fresh refresh token. No site configuration is lost.

Low-data mode

Brand-new or very small sites switch into low-data modeautomatically. The check lives in api/services/site_maturity.py and trips when all three conditions are true:

  • Fewer than 30 GSC query rows in the period
  • Fewer than 10 pages with non-zero GSC impressions
  • Fewer than 500 total GA4 sessions in the period

In low-data mode the analysis engine generates foundation moves — structural publishing and technical recommendations — instead of striking-distance query optimizations. The dashboard hero copy changes to reflect this.

This is not an error. As the site grows, the thresholds will be crossed and the mode will switch automatically on the next analysis run.

Scheduled report didn't arrive

The scheduler in api/services/scheduler.py checks for due schedules every 15 minutes. If a report is late:

  • Check your Google token. If analysis fails because of an expired token, the scheduler catches the exception, logs it, and skips delivery. Re-auth at /login.
  • Check spam. Email reports come from the SignalGuide sending domain via Resend. Add the sender to your contacts if your mail client is filtering them.
  • For Slack: check that the webhook URL is still valid. Slack deactivates webhooks if the app is removed from the channel. See Slack integration.
  • Verify your plan. Scheduled delivery requires a paid plan. The create-schedule endpoint blocks free accounts; if you were downgraded after the schedule was created, the schedule row exists but delivery will still be skipped (the plan check happens at delivery time).

MCP problems

401 Unauthorized on every MCP request

The MCP middleware in api/mcp/app.py rejects requests with no Authorization header or a header that doesn't start with Bearer (note the space). For manual tokens, the token must start with sgm_. OAuth access tokens start with sgoat_.

If you recently regenerated your token, the old one is permanently invalid — tokens are stored only as SHA-256 hashes and cannot be recovered. Generate a new one in Settings → MCP → Manual tokens and update your client config.

Tools not appearing in Claude Desktop

Almost always a JSON syntax error in the config file (trailing comma, mismatched quotes) or Claude Desktop wasn't fully restarted after editing. Validate the JSON, quit Claude Desktop completely from the menu bar, then reopen.

“Site not found” when calling a tool

The tool is being called with a site_id that doesn't belong to the authenticated user. Ask the assistant to call list_sites() first and use a site ID from that response.

Tools return empty data

A fresh site has no snapshot until the first analysis run. Tool responses will include "snapshot": null and empty arrays. Trigger an analysis from the dashboard first, then try the MCP tools again.

Still stuck?
Email support@signalguide.io with your account email and a description of what you tried. Agency plan customers get priority response.

Related: Connecting your data and MCP setup.