Capyseo Logo Capyseo

Troubleshooting

Troubleshooting

Common issues and solutions.

Installation Issues

"Command not found: capyseo"

bash: capyseo: command not found

Solution:

# Use npx/bunx bunx @capyseo/cli analyze ./dist # Or install globally bun add -g @capyseo/cli

"Cannot find module '@capyseo/core'"

Solution:

# Install dependencies bun install # Rebuild bun run build

Peer dependency warnings

WARN unmet peer dependency

Usually safe to ignore for optional features. Install if needed:

bun add cheerio @google/genai

Analysis Issues

"No HTML files found"

Error: No HTML files found in ./dist

Causes:

  1. Wrong directory
  2. Build not run
  3. Files have different extension

Solutions:

# Check directory exists ls -la ./dist # Build first bun run build # Specify pattern capyseo analyze ./dist --pattern "**/*.htm"

"File not found"

Error: ENOENT: no such file or directory

Solution:

# Use absolute path capyseo analyze /full/path/to/dist # Or relative from current directory cd my-project capyseo analyze ./dist

Analysis hangs

Causes:

  1. Very large site
  2. Slow AI responses
  3. Network issues

Solutions:

# Limit pages capyseo analyze ./dist --limit 10 # Disable AI capyseo analyze ./dist --no-ai # Increase timeout capyseo analyze ./dist --timeout 120000

"Score is 0"

All rules failed or no content found.

Check:

  1. HTML files exist and have content
  2. Files aren't just redirects
  3. Config isn't disabling all rules

AI Issues

"No AI provider configured"

Warning: AI suggestions disabled - no API key found

Solution:

# Set API key export GEMINI_API_KEY=your_key # Or specify provider capyseo analyze ./dist --ai --ai-provider gemini

"Invalid API key"

Error: API key not valid

Check:

  1. Key is correct (no extra spaces)
  2. Key is not expired
  3. Key has proper permissions
# Verify key is set echo $GEMINI_API_KEY # Test directly curl https://generativelanguage.googleapis.com/v1/models \ -H "x-goog-api-key: $GEMINI_API_KEY"

"Rate limit exceeded"

Error: 429 Too Many Requests

Solutions:

# Enable caching capyseo analyze ./dist --ai --cache-dir .capyseo-cache # Wait and retry sleep 60 && capyseo analyze ./dist --ai # Use smaller model capyseo analyze ./dist --ai --ai-model gemini-2.5-flash

"Connection refused" (Ollama)

Error: connect ECONNREFUSED 127.0.0.1:11434

Solution:

# Start Ollama server ollama serve # Check it's running curl http://localhost:11434/api/tags

Slow AI responses

Solutions:

  1. Use faster model:

    --ai-model gemini-2.5-flash # instead of pro

  2. Enable caching:

    --cache-dir .capyseo-cache

  3. Limit pages:

    --limit 20

Configuration Issues

"Config file not found"

Warning: Config file not found

Solution:

# Create config capyseo init # Or specify path capyseo analyze ./dist --config ./my-config.js

"Invalid configuration"

Error: Invalid configuration: rules.meta-title

Check config syntax:

// capyseo.config.js export default { rules: { 'meta-title': { // Rule ID (string) severity: 'error', // 'error' | 'warning' | 'info' enabled: true, // boolean }, }, };

Config not loading

Check:

  1. File is named correctly: capyseo.config.js or capyseo.config.ts
  2. Export is default: export default { ... }
  3. No syntax errors
# Test config loads node -e "import('./capyseo.config.js').then(c => console.log(c.default))"

Output Issues

"Cannot write to file"

Error: EACCES: permission denied

Solution:

# Check permissions ls -la ./ # Use different output path capyseo analyze ./dist -o ~/seo-report.json

HTML report blank

Causes:

  1. No issues found (good!)
  2. Output path wrong
  3. File not generated

Check:

# Verify file exists ls -la seo-report.html # Check file size wc -c seo-report.html

JSON parse errors

SyntaxError: Unexpected token

Output may have non-JSON content.

Solution:

# Use --quiet for clean output capyseo analyze ./dist --format json --quiet > report.json

CI/CD Issues

"Exit code 1 but no errors shown"

Score is below threshold.

Check:

# Show score capyseo analyze ./dist --ci --min-score 0 # Lower threshold capyseo analyze ./dist --ci --min-score 50

"Permission denied in CI"

Error: EACCES: permission denied

Solution:

# GitHub Actions - run: chmod +x ./node_modules/.bin/capyseo

Secrets not available

Error: GEMINI_API_KEY is not defined

Check:

  1. Secret is defined in CI settings
  2. Secret name matches env var
  3. Workflow has access to secrets
# GitHub Actions env: GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

Cache not working in CI

# Add cache step - uses: actions/cache@v4 with: path: .capyseo-cache key: capyseo-${{ hashFiles('dist/**/*.html') }}

SvelteKit Issues

"Plugin not loading"

Check vite.config.ts:

import { capyseo } from '@capyseo/adapter-sveltekit'; export default defineConfig({ plugins: [sveltekit(), capyseo()], });

"Hooks not working"

Check src/hooks.server.ts:

import { createCapyseoHandle } from '@capyseo/adapter-sveltekit'; const capyseoHandle = createCapyseoHandle(); export const handle = capyseoHandle; // Or with sequence import { sequence } from '@sveltejs/kit/hooks'; export const handle = sequence(capyseoHandle, yourHandle);

Headers not added

Check:

  1. Response is HTML
  2. Response is successful (2xx)
  3. Headers aren't stripped by hosting

Performance Issues

Analysis very slow

Optimize:

# Limit pages capyseo analyze ./dist --limit 50 # Disable slow rules capyseo analyze ./dist --exclude broken-links # Parallel processing (default) capyseo analyze ./dist --parallel

High memory usage

Solutions:

# Process fewer pages at once capyseo analyze ./dist --concurrency 2 # Limit pages capyseo analyze ./dist --limit 100 # Increase Node memory NODE_OPTIONS="--max-old-space-size=4096" capyseo analyze ./dist

Large output files

Solutions:

# Use summary format capyseo analyze ./dist --format summary # Filter by severity capyseo analyze ./dist --min-severity warning

Getting Help

Debug mode

# Verbose output capyseo analyze ./dist --verbose # Debug logging DEBUG=capyseo:* capyseo analyze ./dist

Check version

capyseo --version

File an issue

Include:

  1. Capyseo version
  2. Node/Bun version
  3. OS and version
  4. Command run
  5. Full error message
  6. Minimal reproduction
# Gather info capyseo --version node --version bun --version uname -a

Quick Fixes Checklist

  • Dependencies installed (bun install)
  • Site built (bun run build)
  • Correct directory (ls dist/*.html)
  • API key set (echo $GEMINI_API_KEY)
  • Config valid (no syntax errors)
  • Permissions correct (read/write access)
  • Network available (for AI/remote checks)