Troubleshooting

Common issues and their solutions when using KodaDocs.

No Routes Discovered

Symptom: KodaDocs reports 0 or very few routes.

Solutions:

• Ensure you're running KodaDocs from your project root directory
• Check that your framework is correctly detected (run kodadocs config . --show)
• If your app uses a non-standard routing pattern, provide --url so the Playwright crawler can discover routes by navigating your running app
• For WordPress sites, use --user and --pass to access admin routes

Screenshots Are Blank

Symptom: Captured screenshots are white or empty.

Solutions:

• Make sure your app is running at the configured app_url
• Check that the app has finished loading (some SPAs need extra time)
• If using authentication, verify your credentials are correct
• Try running with --fresh to clear cached state

"No Module Named 'kodadocs'" Error

Solutions:

• Install KodaDocs: pip install kodadocs
• If using uvx, ensure it's installed: pip install uv
• Check your Python version: KodaDocs requires Python 3.10+

AI Features Not Working

Symptom: Articles are not generated, or product summary is missing.

Solutions:

• Set the ANTHROPIC_API_KEY environment variable
• Check your API key is valid and has sufficient credits
• KodaDocs automatically disables AI features if no API key is found

Build Fails During Output Step

Symptom: npm install or npm run docs:build fails.

Solutions:

• Ensure Node.js 18+ is installed
• Check you have npm available on your PATH
• Try deleting docs/node_modules and running again

Pro Theme Loading Fails

Symptom: Error about invalid license key or theme not found.

Solutions:

• Verify your license key format: kd_pro_*
• Check the key is set via KODADOCS_LICENSE_KEY env var or --license-key flag
• Ensure your Pro subscription is active
• If the API is temporarily down, KodaDocs uses cached themes (valid for 24 hours)

Manifest Issues

Symptom: Pipeline seems stuck or keeps skipping steps.

Solutions:

• Run with --fresh to clear the manifest and start over:

  kodadocs generate . --fresh

• Delete .kodadocs/run_manifest.json manually
• Check .kodadocs/session_config.json for incorrect settings

Playwright Not Installed

Symptom: Screenshot capture fails with Playwright errors.

Solutions:

# Install Playwright browsers
playwright install chromium

Getting Help

If you're still stuck:

• Check the GitHub Issues for known problems
• Open a new issue with your error output and configuration
• Include your framework, Node.js version, and Python version