Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AgricIDaniel/claude-seo/llms.txt

Use this file to discover all available pages before exploring further.

This page covers every known failure mode for Claude SEO and the steps to resolve each one. Issues are organized by symptom. If your issue is not listed here, check docs/ARCHITECTURE.md for structural context, file a bug report on the GitHub repository, or use Claude Code’s internal log output for detailed error traces.

​
Skill and Agent Loading

Symptom: Typing /seo in Claude Code produces “command not found” or no response.Diagnosis: The orchestrator’s SKILL.md is either missing, in the wrong location, or has malformed frontmatter.Fix:
  1. Verify the installation file exists:
ls ~/.claude/skills/seo/SKILL.md
  1. Check that the frontmatter is valid — the file must open with three dashes:
head -5 ~/.claude/skills/seo/SKILL.md
Expected output:
---
name: seo
description: "Comprehensive SEO analysis for any website or business type.
  1. Restart Claude Code (the claude command reloads all skills):
claude
  1. If the file is missing or corrupted, re-run the installer. Download and inspect the script before running it:
curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/install.sh > install.sh
cat install.sh   # review before running
bash install.sh
rm install.sh
Symptom: During a /seo audit, Claude Code reports Agent 'seo-technical' not found or similar for any specialist agent.Diagnosis: The agent markdown files were not copied to ~/.claude/agents/ during install, or were accidentally deleted.Fix:
  1. Verify agent files exist:
ls ~/.claude/agents/seo-*.md
  1. Check an agent’s frontmatter is intact:
head -5 ~/.claude/agents/seo-technical.md
  1. Re-copy agents from the cloned repository:
cp /path/to/claude-seo/agents/*.md ~/.claude/agents/
Or re-run the full installer to restore all files.

​
Python Dependencies

Symptom: A script called during an audit fails with ModuleNotFoundError.Diagnosis: As of v1.2.0, all dependencies are installed into a virtual environment at ~/.claude/skills/seo/.venv/. The venv may not have been created, or a package install may have failed partway through.Fix:Use the venv’s own pip to install from the requirements file:
~/.claude/skills/seo/.venv/bin/pip install -r ~/.claude/skills/seo/requirements.txt
If the venv does not exist yet, fall back to user-space install:
pip install --user -r ~/.claude/skills/seo/requirements.txt
Or install the most commonly missing packages individually:
pip install --user beautifulsoup4 requests lxml playwright Pillow urllib3 validators trafilatura htmldate
Symptom: No such file or directory: requirements.txt even though the install script appeared to complete.Diagnosis: As of v1.2.0 the installer copies requirements.txt to the skill directory. An older installer or a partial install may have missed this step.Fix:Check whether the file landed correctly:
ls ~/.claude/skills/seo/requirements.txt
If it is missing, download it directly:
curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/requirements.txt \
  -o ~/.claude/skills/seo/requirements.txt
Then install:
pip install --user -r ~/.claude/skills/seo/requirements.txt
Symptom: On Windows, running python or pip in PowerShell either fails entirely or invokes Python 2.Diagnosis: The Windows installer (v1.2.0+) tries both python and py -3. If both fail, Python is either not installed or not on the system PATH.Fix:
  1. Install Python 3.10+ from python.org and check “Add Python to PATH” during setup.
  2. Use the Windows launcher to target Python 3 explicitly: 
py -3 -m pip install -r requirements.txt
  1. Or use the python3 -m pip form:
python3 -m pip install -r requirements.txt
  1. If py -3 still fails, verify the Python launcher is installed:
where py
If it is missing, reinstall Python with the launcher option checked.

​
SPA Rendering and Playwright

Symptom: A script fails with playwright._impl._errors.Error: Executable doesn't exist when trying to render a page.Diagnosis: Playwright is installed as a Python package but the Chromium browser binary has not been downloaded yet. The package and the browser are separate installation steps.Fix:
playwright install chromium
If the playwright binary is not on your PATH:
python3 -m playwright install chromium
On a headless Linux server you may also need the system dependencies:
playwright install-deps chromium
Symptom: A React, Next.js, Vue, Nuxt, or Astro site is audited but findings reference an empty <div id="root"> shell rather than actual page content.Diagnosis: --render auto detected the SPA but the page content is hydrated after an interaction (scroll past the fold, tab click, modal open) or behind a race-condition-prone third-party widget mount. The headless renderer captured the DOM before hydration completed.Fix:Manually trigger the seo-visual subagent and compare its Playwright screenshot to the raw-HTML subagent’s findings:
/seo page https://example.com/problematic-page
Then force rendering always on the specific page:
python3 ~/.claude/skills/seo/scripts/render_page.py https://example.com/problematic-page --render always
Review the diff between the two outputs to isolate which findings are artefacts of incomplete hydration vs. genuine SEO issues.

​
Permission Errors

Symptom: Permission denied when running install.sh or executing scripts in the scripts/ directory.Diagnosis: The install script or Python scripts are not marked executable.Fix:
chmod +x ~/.claude/skills/seo/scripts/*.py
For the install script itself:
chmod +x install.sh
bash install.sh

​
Google API Errors

Symptom: Running /seo google produces a 403 error or invalid_grant / unauthorized message.Diagnosis: The credential file may be missing, in the wrong location, have incorrect permissions, or the OAuth token may have expired.Fix:
  1. Verify the credential directory exists and files are present:
ls -la ~/.config/claude-seo/
  1. Check file permissions — all credential files must be 0o600:
chmod 600 ~/.config/claude-seo/*.json
  1. Re-run the credential wizard to refresh the OAuth token:
/seo google setup
  1. For service account authentication, verify the service account has been granted the correct OAuth scopes in the Google Cloud Console (Search Console read access for GSC, https://www.googleapis.com/auth/webmasters.readonly).
  2. To test credential detection without running a full audit: 
python3 ~/.claude/skills/seo/scripts/google_auth.py --check

​
Audit Performance

Symptom: A /seo audit takes more than 15–20 minutes without completing.Diagnosis: Possible causes: the target site has slow server response times (>2s TTFB), the site has many pages and the audit is crawling all of them, or a single subagent is blocked waiting for a slow external API.Fix:
  1. Check if the site itself is slow by timing a single page fetch:
python3 ~/.claude/skills/seo/scripts/fetch_page.py https://example.com
  1. For faster checks on specific concerns, use targeted sub-skills instead of the full audit:
/seo page https://example.com           # single-page analysis
/seo technical https://example.com      # technical SEO only
/seo schema https://example.com         # schema only
  1. Note that full site audits crawl up to 500 pages. Large sites with many URLs will take longer regardless. Subagents run in parallel to reduce total time, but network round-trips to a slow origin are the dominant bottleneck.
  2. Some sites block automated requests or return 429 rate-limit responses. Check the audit output for HTTP error codes and add a delay if needed.
Symptom: The seo-schema audit flags schema markup as invalid that passes Google’s Rich Results Test manually.Diagnosis: The schema block may contain placeholder text that was not replaced, an @context URL with a trailing slash, or a type that is valid for non-Google purposes but is in the Claude SEO deprecated-types list.Fix:
  1. Ensure all template placeholders in generated JSON-LD blocks are replaced with real values.
  2. Verify @context is exactly https://schema.org (no trailing slash, no http://).
  3. Check for deprecated types (HowTo, SpecialAnnouncement, ClaimReview, VehicleListing, EstimatedSalary, LearningVideo, CourseInfo carousel). These produce Critical findings by design in v2 — consult skills/seo-schema/references/deprecated-types-2024-2026.md for replacement guidance.
  4. Validate independently at Google’s Rich Results Test to confirm whether the finding is a Claude SEO false positive or a genuine issue.
  5. If you need to suppress a finding for a type you are intentionally keeping for non-Google purposes, remove that type from the deprecated list in the local seo-schema skill file. Document the reason in a comment.

​
Debug Mode

To test individual scripts directly and see raw output: 
# Test page fetching
python3 ~/.claude/skills/seo/scripts/fetch_page.py https://example.com

# Test HTML parsing
python3 ~/.claude/skills/seo/scripts/parse_html.py page.html --json

# Test headless rendering
python3 ~/.claude/skills/seo/scripts/render_page.py https://example.com --render auto

# Test Playwright screenshots
python3 ~/.claude/skills/seo/scripts/capture_screenshot.py https://example.com

# Test Google credential detection
python3 ~/.claude/skills/seo/scripts/google_auth.py --check
All scripts output JSON by default (--json flag), making it straightforward to pipe their output to jq for inspection.

​
Getting Help

GitHub Issues

File a bug report with your operating system, Python version, Claude SEO version, and the full error message.

Architecture Reference

Review the 3-layer architecture and directory structure to understand where files are expected to live.

Build docs developers (and LLMs) love

Get started for freeTalk to us