Troubleshooting

Common issues and solutions for Share of Search analysis.

Installation Issues

Missing Dependencies

Problem: ImportError when running the analysis

Solution:

pip install -r requirements.txt

Sphinx Build Errors

Problem: Documentation build fails

Solution:

cd docs
pip install -r requirements-docs.txt
make clean html

API Configuration

SerpAPI Key Not Found

Problem:

ERROR: API key not found in environment variable: SERPAPI_KEY

Solution: Create a .env file in the project root:

SERPAPI_KEY=your_key_here

Rate Limit Errors

Problem: Too many API requests

Solution:

  • Increase retry_delay in config.yaml

  • Enable caching: cache_enabled: true

  • Reduce query frequency

Data Issues

No Data Returned

Problem: Empty results from Google Trends

Solution:

  • Check query spelling

  • Verify geographic region code

  • Try broader date range

  • Ensure queries have sufficient search volume

Incomplete Time Series

Problem: Missing data points in output

Solution:

  • Google Trends may not have data for all periods

  • Try different granularity (monthly instead of daily)

  • Check for low-volume queries

AI Insights

OpenAI API Errors

Problem: No insights generated

Solution:

  1. Verify OPENAI_API_KEY in .env

  2. Check analysis.insights.enabled: true in config

  3. Review API quota limits

  4. Check logs for detailed error messages

Visualisation Issues

Charts Not Generated

Problem: Missing PNG files

Solution:

  • Check matplotlib installation: pip install matplotlib

  • Verify output directory permissions

  • Review logs for errors

PowerPoint Generation Failed

Problem: PPTX file not created

Solution:

  • Install python-pptx: pip install python-pptx

  • Check template files exist

  • Verify output directory writable

Performance

Slow Analysis

Solutions:

  • Enable caching to avoid redundant API calls

  • Reduce date range for faster processing

  • Use monthly granularity instead of daily

  • Disable AI insights if not needed

Logs

Finding Logs

Detailed logs are saved to:

outputs/[project_name]/analysis.log

Set log level in config.yaml:

options:
  log_level: "DEBUG"  # or INFO, WARNING, ERROR

Getting Help

If issues persist:

  1. Check logs in outputs/*/analysis.log

  2. Review configuration against examples

  3. Consult GitHub Issues

  4. Verify all dependencies are installed