PageBridge

Troubleshooting

Common issues and how to resolve them.

list-sites returns no sites

The service account does not have access to any GSC properties.

  • Open Google Search Console
  • Go to property settings > Users and permissions
  • Add the service account email with Full permissions
  • Wait a few minutes for permissions to propagate

Authentication errors

If you see Error: Could not load the default credentials or similar:

  • Verify GOOGLE_SERVICE_ACCOUNT is valid JSON
  • Check that newlines in the private key are properly escaped as \n
  • Ensure the Search Console API is enabled in your Google Cloud project
# Test JSON validity
echo $GOOGLE_SERVICE_ACCOUNT | jq .
bash

No data in Performance pane

The Performance tab shows an empty state. Possible causes:

  1. Sync has not been run — run pagebridge sync --site ...
  2. URL not matched — check if the page was matched using pagebridge diagnose --site ...
  3. No impressions — the page may have zero search impressions in the last 90 days
  4. Wrong content type — ensure the document type is listed in the gscSite urlConfigs

Many unmatched URLs

A high number of unmatched URLs is normal. These typically include:

  • Homepage and category/tag pages (outside the path prefix)
  • Pages for document types not configured in contentTypes
  • Old URLs for deleted or redirected content
  • Pagination URLs, archive pages, etc.

Focus on no_matching_document results — these are URLs that should have matching content but don't:

pagebridge diagnose --site sc-domain:example.com --reason no_matching_document
bash

Common fixes:

  • Slug mismatch — the URL slug differs from the Sanity slug.current value. Check for typos, hyphens vs underscores, or casing.
  • Wrong slugField — the slugField in gscSite does not match the actual field name on your documents.
  • Draft documents — Sanity drafts are not published and may not be queryable with the default token permissions.

Database connection issues

  • Verify the DATABASE_URL format: postgresql://user:password@host:port/database
  • For hosted databases, ensure ?sslmode=require is appended
  • Check that the database server is reachable from your network
  • Ensure the schema has been pushed: pnpm db:push

GSC API rate limits

Google Search Console API has rate limits. If you encounter 429 Too Many Requests:

  • The sync automatically paginates at 25,000 rows per request
  • Index status checks are rate-limited to 100ms between requests (600/min)
  • If you hit limits, wait a few minutes and retry
  • For very large sites, consider syncing during off-peak hours

False positive decay signals

If you see decay signals for content that should not be flagged:

  • New content — increase the quiet period: --quiet-period 60
  • Seasonal content — some pages naturally fluctuate. Dismiss or snooze these tasks in the Refresh Queue.
  • Low traffic pages — raise the minImpressions threshold in custom DecayDetector rules

Still stuck?

Open an issue on GitHub with:

  • The command you ran
  • The error output (with --debug flag)
  • Your Node.js version and OS