Troubleshooting

Troubleshooting

PageSpeed Fails With a Rate Limit

Treat this as an environment limitation, not a confirmed site issue.

Recommended handling:

• Retry once.
• If it still fails, mark Core Web Vitals as Hypothesis or Unknown.
• Continue the audit with available page evidence.

GitHub API Calls Fail

Use provider fallback:

python3 scripts/github_repo_audit.py --repo owner/repo --provider auto --json

Authenticate with either:

export GITHUB_TOKEN="..."

or:

gh auth login -h github.com

Playwright or Screenshot Checks Fail

Install Chromium:

python3 -m pip install playwright
python3 -m playwright install chromium

If the environment does not support browsers, report visual findings as blocked instead of confirmed.

Reference Freshness CI Fails

Run:

python3 scripts/reference_freshness.py resources/references --max-age-days 90

Fix missing, invalid, or future-dated markers.

Stale references are warnings unless --fail-stale is used.

Installed Skill Inventory Fails

Run:

python3 scripts/validate_skill_inventory.py

The expected inventory is 16 skills, 10 agents, and 89 scripts.

Noindex Pages Appear as SEO Problems

Noindex pages should not be treated the same as indexable pages for thin-content or duplicate-content findings. Findings against noindex pages should be skipped or clearly downgraded.

Next.js Image Fill False Positives

Next.js <Image fill> outputs images with data-nimg="fill" and no fixed width or height attributes. These images are layout-constrained by CSS and should not be flagged as ordinary missing-dimension CLS risks.