Troubleshooting Guide

This guide helps you identify and resolve the most common issues you may encounter while using SEO Watcher. Every solution is described using the menus, sidebars, and settings available inside Google Sheets — no code editing required.

1. Scans Stopping Mid-Way on Large Sheets

This is the most frequently reported issue and it is important to understand why it happens and how to solve it permanently.

What You See

  • You click Run update and receive an alert saying the update completed, but many checks in your results sheet show a status of “failed” with one of these messages:
    • TIME LIMIT REACHED: Upgrade to PRO to remove execution time limits
    • LICENSE LIMIT REACHED: Upgrade to PRO to run > 50 checks
  • Alternatively, the script stops without any alert and your results sheet is incomplete.

Why It Happens

SEO Watcher runs inside Google Apps Script, Google’s free server-side environment for Sheets extensions. Google enforces a hard 6-minute execution limit on every script run — this is a platform restriction that affects all Google Sheets extensions, not just SEO Watcher.

When your spreadsheet contains many URLs and checks, the script may not be able to process all of them within that 6-minute window. In the Free version, two things can happen:

  1. Check-count limit (50 checks): The Free plan processes up to 50 checks per run. Any checks beyond that limit are immediately marked as failed.
  2. Time limit (~5.5 minutes): Even if you have fewer than 50 checks, some checks (especially SERP lookups or slow-loading URLs) take longer to process. If the cumulative execution time reaches approximately 5.5 minutes, the remaining checks are marked as failed to prevent Google from forcibly killing the script.

In both cases, the checks that were not processed are not lost — they remain in the checks sheet and can be run again. However, each new run faces the same limitations.

The Solution: Upgrade to PRO and the Watchdog Engine

The PRO version eliminates both limitations entirely through the Watchdog engine:

Free Version PRO Version
Maximum checks per run 50 Unlimited
Time limit handling Remaining checks fail Watchdog auto-resumes
Manual re-runs needed Yes No — fully automatic
Large sheets (100+ checks) Incomplete results Every check completes

How the Watchdog works:

  1. When you start an update, the Watchdog monitors execution time in the background.
  2. At approximately the 4.5-minute mark (safely before Google’s 6-minute cut-off), the Watchdog pauses execution.
  3. It saves your exact progress — which URL it was processing, how many checks were completed, and all accumulated data.
  4. It automatically schedules a new run that picks up exactly where it left off.
  5. This cycle repeats as many times as necessary until every single check is completed.
  6. Once all checks are done, the email report is sent (if configured).

The result: whether you have 50 checks or 500, the PRO Watchdog completes them all with zero manual intervention. You click Run update once and walk away. The Watchdog handles the rest.

How to Upgrade

  1. Go to Extensions > 🧿 SEO Watcher 🧿 > Settings > Manage License.
  2. Click the purchase link to get a PRO subscription.
  3. Enter your license key and click Activate License.
  4. Your Watchdog engine is now active — run your update and all checks will complete automatically.

2. Authorization & Permissions

“Authorization required” Error

What you see: An alert with “Missing permissions for: [action]. Check script authorizations.”

Why it happens: Google requires you to authorize the extension before it can access your spreadsheet, send emails, or connect to external services. This authorization may have expired or was never completed.

How to fix it:

  1. Go to Extensions > 🧿 SEO Watcher 🧿 and click any menu item (e.g., Setup Wizard).
  2. Google will display an authorization prompt. Click Continue.
  3. Select your Google account.
  4. If you see “This app isn’t verified”, click Advanced at the bottom left, then click Go to SEO Watcher (unsafe). This is a standard Google warning for all custom extensions and does not indicate any actual risk.
  5. Review the permissions and click Allow.

You only need to authorize once per spreadsheet. If you copy the spreadsheet to a new file, you will need to authorize again.

“Service invoked too many times” Error

What you see: An alert with “Request limit reached during: [action]. Retry in a few minutes.”

Why it happens: Google Apps Script enforces daily quotas on certain operations (e.g., URL fetches, email sends). If you run many updates in a short period, you may temporarily hit these limits.

How to fix it:

  1. Wait a few minutes and try again.
  2. If the issue persists, wait until the next day when quotas reset.
  3. Consider spacing out your updates or using Schedule Updates (PRO) to distribute checks across the day.

3. Google Search Console (GSC) Issues

“GSC integration is disabled”

What you see: Your index_status checks fail, or you see an alert saying “GSC integration is disabled.”

How to fix it:

  1. Go to Extensions > 🧿 SEO Watcher 🧿 > Settings > Search Console > Configure GSC.
  2. Make sure the Enable GSC integration checkbox is checked.
  3. Click Save.

“OAuth not authorized” / GSC Not Connected

What you see: The message “OAuth not authorized. Please Authorize in GSC Configuration” appears in your error log or check results.

How to fix it:

  1. Go to Extensions > 🧿 SEO Watcher 🧿 > Settings > Search Console > Configure GSC.
  2. Select the OAuth tab.
  3. Click Authorize with Google.
  4. Complete the sign-in flow and grant the requested permissions.
  5. The status should change to Connected (green indicator).
  6. Click Save.

“GSC Service Account credentials missing”

What you see: Checks fail with “GSC Service Account credentials missing.”

How to fix it:

  1. Go to Extensions > 🧿 SEO Watcher 🧿 > Settings > Search Console > Configure GSC.
  2. Select the Service Account tab.
  3. Enter your Service Account Email (format: name@project.iam.gserviceaccount.com).
  4. Paste your Private Key in PEM format (must include the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- lines).
  5. Click Test Connection to verify.
  6. If the test succeeds, click Save.

“Invalid JWT” / Token Errors

What you see: GSC checks fail with “Invalid JWT” or “GSC SA Token Error” in the error log.

Why it happens: The private key was not pasted correctly, or it has formatting issues.

How to fix it:

  1. Go to Extensions > 🧿 SEO Watcher 🧿 > Settings > Search Console > Configure GSC.
  2. Open your JSON key file with a text editor.
  3. Copy the entire private_key value, including all n characters.
  4. Paste it into the Private Key field. The extension will automatically clean up escaped newlines and surrounding quotes.
  5. Click Test Connection to verify the key works.

“Permission denied” / “unauthorized_client”

What you see: GSC checks fail with “Permission denied” or “unauthorized_client.”

How to fix it:

  1. Verify the Search Console API is enabled in your Google Cloud Console project.
  2. Open Google Search Console.
  3. Go to Settings > Users and permissions.
  4. Confirm that your service account email (or your OAuth Google account) is listed with at least Full or Owner permission.
  5. If not listed, click Add user, paste the email, and grant Full permission.

“No Properties Found”

What you see: The List Properties dialog shows “No Search Console properties found.”

How to fix it:

  • If using OAuth: Make sure the Google account you authorized has at least one property in Search Console.
  • If using Service Account: Add the service account email as a user to each GSC property you want to monitor (see the step above).

4. SerpApi Issues

“Missing SerpApi Key”

What you see: SERP checks fail with “Missing SerpApi Key. Configure it in Menu > Configure SerpApi.”

How to fix it:

  1. Go to Extensions > 🧿 SEO Watcher 🧿 > Settings > SerpApi.
  2. Enter your SerpApi API key in the field.
  3. Click Save Configuration.

If you do not have an API key, sign up at serpapi.com to get one.

“SerpApi Error (401)” or “SerpApi Error (429)”

What you see: SERP checks fail with a status code error from SerpApi.

Common causes and fixes:

Error Code Meaning Solution
401 Invalid API key Go to Settings > SerpApi and re-enter a valid key
429 Rate limit exceeded You have exceeded your SerpApi plan’s search quota. Wait or upgrade your SerpApi plan
403 Account issue Check your SerpApi account status at serpapi.com

SERP Checks Show “failed” but the Page Ranks

Why it happens: SERP checks are position-sensitive. If you selected top3 as the threshold but your page ranks at position 5, the check will report “failed” because the page is outside the top 3.

How to fix it:

  1. Open the checks sheet in your spreadsheet.
  2. Find the relevant SERP check row.
  3. Change the element column value to a broader threshold (e.g., top5 or top10) if appropriate.

5. Sheet & Data Errors

“Sheet ‘checks’ not found” / “Sheet ‘results_log’ not found”

What you see: An alert with “Sheet ‘checks’ not found. Please run Init sheet first.” or similar messages for other required sheets.

How to fix it:

  1. Go to Extensions > 🧿 SEO Watcher 🧿 > Setup Wizard.
  2. The wizard will re-create any missing sheets with the correct column headers. If a sheet already exists, it will not be overwritten.

This creates all required sheets: checks, results, results_log, header, and error_log.

Important: Never rename or delete these sheets. SEO Watcher relies on the exact sheet names to function.

“All fields except modifier are required”

What you see: You receive this error when trying to save a new check.

How to fix it:

  1. In the Insert Check sidebar, make sure you have filled in all four required fields:
    • URL (must include http:// or https://)
    • Check Type
    • Element
    • Expected Value
  2. The Function/Modifier field is the only optional one.
  3. Click Save again after filling in the missing fields.

“No results to organize”

What you see: The update completes but an error says “No results to organize.”

Why it happens: The results_log sheet is empty or contains only headers. This can occur if the update did not successfully execute any checks.

How to fix it:

  1. Verify the checks sheet has at least one check defined (row 2 and below).
  2. Run the update again via Extensions > 🧿 SEO Watcher 🧿 > Run Update.
  3. If the problem persists, check the error_log sheet for any underlying errors that may have prevented checks from running.

6. URL Fetching & Network Errors

“Unable to fetch URL” / “Exception: Address unavailable”

What you see: Checks for a specific URL fail with “Unable to fetch URL” or “URL unreachable.”

Possible causes and fixes:

  1. The URL is incorrect: Open the checks sheet and verify the URL is complete and valid (includes https://).
  2. The website is down: Try opening the URL in your browser. If it is unreachable, the check will fail until the site is back online.
  3. Firewall or bot protection: Some websites block requests from Google’s server infrastructure. See below.

Website Blocks Google Apps Script Requests

What you see: Checks return errors or unexpected content for sites protected by Cloudflare, WAF, or similar services.

How to fix it:

  1. Open the header sheet in your spreadsheet.
  2. Add a row with a custom User-Agent value (e.g., SEOWatcher/1.0 (monitoring)).
  3. If you control the website, whitelist Google Apps Script IP ranges in your firewall or CDN settings.

“Request failed” / “Timeout”

What you see: “Request failed in: [action]. Check connection and URL.” or “Timeout during: [action].”

Why it happens: The target URL took too long to respond, or there was a network issue on Google’s side.

How to fix it:

  1. Verify the URL loads correctly in your browser.
  2. If the URL consistently times out, the page may be too slow for Google’s fetch timeout. Consider checking a faster-loading page on the same domain.
  3. Run the update again — transient network issues often resolve on the next attempt.

“Exception: Invalid XML”

What you see: Sitemap or ping checks fail with “Invalid XML content.”

How to fix it:

  1. Open the sitemap or RSS feed URL in your browser.
  2. Verify it returns valid XML. Common issues include:
    • HTML error pages instead of XML content.
    • Malformed XML tags.
    • BOM (byte order mark) characters at the start of the file.
  3. Correct the XML source, or update the URL in the checks sheet to point to a valid XML feed.

7. Email Report Issues

Emails Not Being Sent

What you see: Updates complete but you never receive an email report.

Checklist:

  1. Go to Extensions > 🧿 SEO Watcher 🧿 > Settings > Email Reports.
  2. Verify that Enable email reports is checked.
  3. Verify that the Recipients field contains at least one valid email address.
  4. Check your filter settings:
    • If Send only when changes detected is enabled, emails are skipped when no check results changed since the last run.
    • If Send only when failures detected is enabled, emails are skipped when all checks passed.
  5. Click Send Test to verify email delivery. Check your spam/junk folder if the test email does not arrive in your inbox.

“Invalid email format”

What you see: “Invalid email format: [address]” when saving email configuration.

How to fix it:

  1. In the Email Reports modal, check each recipient address for typos.
  2. Multiple addresses must be separated by commas (e.g., alice@example.com, bob@example.com).
  3. Remove any trailing commas or extra spaces.

“Error sending test email”

What you see: The test email fails with a generic error.

Why it happens: Google Apps Script has daily email sending quotas. You may have reached the limit, or the extension may not have email-sending permissions.

How to fix it:

  1. Re-authorize the extension (see Authorization & Permissions).
  2. If quotas are exhausted, wait until the next day.

8. License & PRO Features

“Invalid license key”

What you see: After entering a license key in Manage License, the status remains FREE and the message says “Invalid license key.”

How to fix it:

  1. Copy the license key directly from your Gumroad purchase confirmation email.
  2. Make sure there are no extra spaces before or after the key.
  3. Paste it into the License Key field in Extensions > 🧿 SEO Watcher 🧿 > Settings > Manage License.
  4. Click Activate License.

“License has been refunded or chargebacked”

What you see: Your license was valid but has now been rejected.

Why it happens: The license key is linked to a purchase that was refunded or disputed. SEO Watcher re-verifies licenses every 24 hours and will reject revoked purchases.

How to fix it:

  1. If this was unintentional, contact Gumroad support to resolve the refund/chargeback.
  2. Alternatively, purchase a new PRO subscription and activate the new key.

“Verification failed. Please try again later.”

What you see: The license activation dialog shows a network error.

Why it happens: The license verification server (Gumroad) was temporarily unreachable.

How to fix it:

  1. Wait a few minutes and try activating again.
  2. If the issue persists, check your internet connection and try from a different network.

Note: If your license was previously verified and a re-verification fails due to a network error, SEO Watcher will trust the cached result and continue operating in PRO mode. Your workflow is not interrupted by transient network issues.

9. Scheduled Updates Issues

“Scheduled updates require a Pro license”

What you see: You try to save a schedule but receive “Scheduled updates require a Pro license.”

How to fix it:

  1. Go to Extensions > 🧿 SEO Watcher 🧿 > Settings > Manage License and activate a PRO license.
  2. Return to Extensions > 🧿 SEO Watcher 🧿 > Settings > Schedule Updates and configure your schedule.

Scheduled Updates Not Running

What you see: You configured a schedule but updates are not running at the expected times.

Checklist:

  1. Go to Extensions > 🧿 SEO Watcher 🧿 > Settings > Schedule Updates and verify the schedule is enabled.
  2. Make sure at least one hour is selected in the schedule.
  3. Verify your PRO license is still active in Settings > Manage License.
  4. If your license expired or was deactivated, scheduled triggers are automatically removed. Re-activate your license and re-save the schedule.

Scheduled Update Only Partially Completes

What you see: Scheduled runs produce incomplete results in the results sheet.

Why it happens: This should not happen with an active PRO license, because the Watchdog engine handles time limits automatically. If you see partial results:

  1. Verify your PRO license is still active in Settings > Manage License.
  2. Check the error_log sheet for any errors that occurred during the scheduled run.
  3. If the license is valid, the Watchdog should be creating continuation triggers automatically. The results will be complete once all chained runs finish.

10. Quick Reference: Error Messages

Below is a lookup table of the most common error messages, what they mean, and where to go to fix them.

Error Message Meaning Where to Fix
TIME LIMIT REACHED: Upgrade to PRO to remove execution time limits Google’s 6-minute execution limit was reached (Free version) Settings > Manage License — upgrade to PRO for automatic Watchdog resumption
LICENSE LIMIT REACHED: Upgrade to PRO to run > 50 checks Free plan’s 50-check cap reached Settings > Manage License — upgrade to PRO for unlimited checks
Missing SerpApi Key. Configure it in Menu > Configure SerpApi No SerpApi API key configured Settings > SerpApi — enter your API key
SerpApi Error (401) Invalid SerpApi API key Settings > SerpApi — re-enter a valid key
SerpApi Error (429) SerpApi rate limit exceeded Wait or upgrade your SerpApi plan
GSC integration is disabled GSC not enabled in settings Settings > Search Console > Configure GSC — enable the checkbox
OAuth not authorized GSC OAuth flow not completed Settings > Search Console > Configure GSC — click Authorize with Google
GSC Service Account credentials missing SA email or private key not configured Settings > Search Console > Configure GSC — enter SA credentials
GSC SA Token Error / Invalid JWT Private key pasted incorrectly Settings > Search Console > Configure GSC — re-paste the full private key
Permission denied / unauthorized_client GSC account lacks property access Add your account/SA email to GSC property with Full permission
Sheet 'checks' not found Required sheets not initialized Run the Setup Wizard from the main menu
Unable to fetch URL / Address unavailable Target URL unreachable Verify URL in checks sheet; check if site is online
Request failed / Timeout Network error or slow response Retry the update; check if URL loads in browser
Invalid XML content Sitemap or RSS feed has malformed XML Verify the XML source URL returns valid XML
Authorization required Google script permissions expired Click any menu item to re-trigger the authorization flow
Service invoked too many times Google daily quota reached Wait a few minutes or until the next day
Invalid license key License key not recognized Re-copy key from Gumroad email; check for extra spaces
Scheduled updates require a Pro license Attempting to schedule without PRO Settings > Manage License — activate a PRO key first

Still Need Help?

If your issue is not covered in this guide:

  1. Check the error_log sheet in your spreadsheet for detailed error messages and stack traces.
  2. Review the Installation Guide for setup instructions.
  3. Review the Insert Check Guide for check configuration details.
  4. Review the Sheet Overview Guide for complete documentation of every sheet, column, and data flow.
  5. Review the Features Overview for a full description of every capability.
  6. Review the FAQ for general questions about how SEO Watcher works.

Summary

→ Index