Managing and Troubleshooting GSC Connection

Managing Your GSC Connection

Connection Status Indicators

Connected (Green Badge)

  • ✅ OAuth tokens valid
  • ✅ API access working
  • ✅ Data syncing normally
  • Action: None needed

Disconnected (Yellow Badge)

  • ⚠️ OAuth tokens expired or revoked
  • ⚠️ Connection lost
  • ⚠️ Data not syncing
  • Action: Reconnect using "Connect to Google Search Console" button

Error (Red Badge)

  • ❌ Connection failed
  • ❌ API errors
  • ❌ Permission issues
  • Action: Check error message, run diagnostics, or reconnect

Testing Your Connection

To verify GSC is working properly:

  1. Go to FreshRank AI → Settings → Google Search Console
  2. Click "Test Connection" button
  3. Check result:
    • ✅ Success: "GSC connection is working properly"
    • ❌ Error: See error message and troubleshooting section below

Running Diagnostics

If you're having issues, use the diagnostics tool:

  1. Go to FreshRank AI → Settings → Google Search Console
  2. Click "Run Diagnostics" button
  3. Review the diagnostic report:
    • OAuth token status
    • API access verification
    • Property matching check
    • Recent data fetch status
    • Error logs (if any)

Disconnecting GSC

To disconnect Google Search Console:

  1. Go to FreshRank AI → Settings → Google Search Console
  2. Click "Disconnect" button
  3. Confirm disconnection

What Happens:

  • OAuth tokens are revoked
  • Connection status shows "Disconnected"
  • Priority scores stop updating (existing scores remain)
  • GSC data is cleared after 24 hours
  • You can reconnect anytime

💡 Note: Disconnecting GSC does NOT affect your analysis results, drafts, or any content. Only priority scores are affected.

Known Google Search Console Connection Issues

Most Google Search Console connection problems fall into a small number of known cases.

If you’re seeing an error message, you can jump directly to the relevant solution below.

👇 Jump to a specific issue:

"No matching Google Search Console property found"

Problem: FreshRank can't find your site in GSC after authorization.

Possible causes:

  1. Site URL doesn't match any GSC property
  2. Wrong GSC account connected
  3. Property not verified in GSC
  4. Using URL property but site has different protocol (http vs https)

Solutions:

Check Property Match:

  1. Go to search.google.com/search-console
  2. Note your property URL exactly (including http/https and www/non-www)
  3. Compare to your WordPress site URL in Settings → General → Site Address
  4. They must match exactly

Property Types:

  • URL Property (https://example.com): Must match exactly
  • Domain Property (sc-domain:example.com): Works for all subdomains and protocols

If using URL property:

  • Verify http vs https matches
  • Verify www vs non-www matches
  • Create a domain property if you need flexibility

If using domain property:

  • Should work automatically for any subdomain
  • Verify domain property is properly verified in GSC

If multiple properties exist:

  • FreshRank selects best match automatically
  • Run diagnostics to see which property was selected
  • If wrong property selected, remove unused properties from GSC

"CSRF validation failed"

Problem: Error appears during OAuth authorization flow.

Cause: OAuth state parameter missing, expired, or tampered with.

Solutions:

  1. Don't reuse old OAuth URLs - Start fresh from Settings page
  2. Complete authorization in one session - Don't leave it incomplete
  3. Clear browser cache and try again
  4. Disable browser extensions that might interfere with OAuth
  5. Try different browser if problem persists

"Failed to refresh token"

Problem: Connection shows as disconnected; refresh token expired.

Cause: OAuth refresh token expired (happens after ~7 days of inactivity) or was revoked.

Solutions:

  1. Reconnect GSC - Click "Connect to Google Search Console" button
  2. Complete OAuth flow again - Reauthorize FreshRank
  3. Don't revoke permissions in Google account - This breaks the connection

To prevent future issues:

  • FreshRank auto-refreshes tokens regularly if data syncs happen
  • Connection remains active as long as site is actively using GSC integration
  • Inactive sites (no data fetches) may see token expiration

"API error (HTTP 403): Forbidden"

Problem: FreshRank can't access GSC data despite being connected.

Cause: Insufficient permissions in Google Search Console.

Solutions:

Verify Your GSC Permissions:

  1. Go to search.google.com/search-console
  2. Click on your property
  3. Go to Settings → Users and permissions
  4. Check your role - you need Owner or Full User
  5. If you're "Restricted Access" - this won't work

If you don't have sufficient permissions:

  1. Ask the property owner to upgrade your access
  2. Or ask the owner to connect their GSC account to FreshRank
  3. Restricted access cannot use GSC API

Connection Works But No Priority Scores

Problem: GSC connected successfully but priority scores aren't showing.

Possible causes:

  1. You haven’t started prioritization yet
  2. No GSC data - Posts have no impressions/clicks
  3. Site too new - Less than 3 months in GSC
  4. Data fetch failed - Background process error

Solutions:

Start article prioritization:

  1. Go to dashboard
  2. Click "Prioritize" button in bulk actions
  3. This triggers manual GSC data fetch
  4. Wait until the prioritization finishes and refresh the page

Wait for initial data fetch (can take long on large websites):

  1. GSC data is fetched in background
  2. Check back after a few hours
  3. Priority scores will appear as data processes

Verify posts have GSC data:

  1. Check GSC directly - do posts have impressions?
  2. Posts with zero traffic get low/no priority scores
  3. Very new sites may not have enough data yet

Check for errors:

  1. Go to Settings → Debug tab
  2. Enable debug mode temporarily
  3. Check for GSC-related errors in log
  4. Contact support if errors appear

Priority Scores Seem Wrong

Problem: Priority scores don't match your expectations.

Explanation: Priority scores are calculated algorithmically and might not match your intuition.

Understanding the calculation:

  • Not based on absolute traffic - High-traffic posts might have low scores if stable
  • Emphasizes change - Declining traffic gets high scores
  • Values potential - High impressions + low clicks = opportunity
  • Considers age - But only if content is old enough (60+ days)

Common "surprising" scores:

High-traffic post with low score:

  • Traffic is stable (no decline) = low score
  • Post is recent (< 60 days) = low score
  • This is correct - it doesn't need urgent attention

Low-traffic post with high score:

  • Traffic is declining significantly (even if small) = high score
  • Very old content (2+ years) = high score
  • This is correct - it needs attention before it dies

If scores genuinely seem incorrect:

  1. Run diagnostics to check GSC data
  2. Verify date setting (Published vs Modified) is appropriate
  3. Check if GSC data is current (should update daily)
  4. Contact support with specific examples

"Rate limit exceeded" Error

Problem: GSC data fetch fails with rate limit error.

Cause: Too many API requests to GSC in short time.

Solutions:

  1. Wait 10-15 minutes and try again
  2. Avoid bulk operations - Don't click "Prioritize" repeatedly
  3. GSC API has daily quotas - Rare to hit but possible on huge sites
  4. Data is cached 24 hours - Subsequent requests use cache

Prevention:

  • FreshRank adds 300ms delays between API calls automatically
  • Data caching reduces API usage
  • Bulk operations spread out requests

OAuth Token Keeps Expiring

Problem: Need to reconnect GSC every few days.

Cause: Refresh token not being used or stored properly.

Solutions:

Verify OAuth credentials are correct:

  1. Check Client ID and Client Secret in Settings
  2. Ensure they're from the same Google Cloud project
  3. Verify credentials weren't regenerated in Google Cloud Console

Ensure encryption is working:

  1. FreshRank encrypts OAuth tokens in database
  2. If encryption fails, tokens may not persist
  3. Check that OpenSSL PHP extension is enabled
  4. Contact support if encryption issues suspected

Check for token revocation:

  1. Go to myaccount.google.com/permissions
  2. Verify "FreshRank AI" app is listed
  3. If missing, you manually revoked it - don't do this
  4. Reconnect through FreshRank Settings

Token refresh error: Unauthorized

Problem:

FreshRank shows a token refresh error with message Unauthorized.

What this means:

FreshRank is trying to use an existing OAuth refresh token, but Google has rejected it. This indicates that the stored authorization token is no longer valid and cannot be refreshed.

Common causes:

  • The Google OAuth app was previously in Testing mode and the user was not yet added as a test user
  • The user added themselves as a test user after an initial failed or incomplete authorization
  • OAuth permissions were changed after the original connection
  • The app access was revoked or partially revoked in the Google account
  • The OAuth flow was interrupted or completed under invalid app state

⚠️ Adding yourself as a test user does not retroactively fix already-issued tokens.

Why this happens:

Once Google marks a refresh token as invalid, it cannot be reused. FreshRank will continue to receive “Unauthorized” errors until a brand-new OAuth authorization is completed.

Solution: Reset the Google authorization

  1. Go to https://myaccount.google.com/permissions
  2. Find the OAuth app you created for Google Search Console. If you followed our GSC setup guide it should be called "FreshRank".
  3. Click on Delete all connections that you have with FreshRank/YourAppName
  4. Confirm that you want to delete the connection.
  5. Go back to FreshRank AI → Settings → Google Search Console
  6. Click Disconnect (if connected)
  7. Click Connect to Google Search Console
  8. Complete the OAuth flow from start to finish

This creates a new authorization grant and a valid refresh token.

"Access blocked: app has not completed the Google verification process" (Error 403)

Problem:

During Google Search Console authorization, Google shows this error:

Access blocked: <app name> has not completed the Google verification process

The app is currently being tested, and can only be accessed by developer-approved testers.

Error 403: access_denied

What this means:

The Google OAuth app you created is still in Testing mode, and the Google account you’re using is not allowed to access it.

This is expected Google behavior and does not indicate a problem with FreshRank or your Search Console setup.

Common causes:

  • OAuth app is in Testing mode
  • Your Google account is not added as a Test user
  • OAuth consent screen setup was not completed
  • App was never published to Production

Solution (choose one):

Option 1: Add yourself as a test user (fastest)

  1. Go to Google Cloud Console
  2. Open APIs & Services → OAuth consent screen
  3. Click Audience
  4. Under Test users, add your Google email
  5. Save and retry the connection in FreshRank

Option 2: Publish the app (recommended)

  1. Go to APIs & Services → OAuth consent screen
  2. Click Audience
  3. If status is Testing, click Publish app

Important notes:

  • Publishing the app does not expose your data
  • Users must still explicitly grant access
  • Publishing does not force re-authentication
  • If you previously attempted to connect before fixing this, you may need to disconnect and reconnect FreshRank

If you see this error after adding yourself as a test user:

Follow the “Token refresh error: Unauthorized” steps above to reset the authorization.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us