Troubleshooting

Configuration fails

Use the supported fields. Older templates contained inactive settings that now raise validation errors. Remove them. Check that query names and labels are unique and non-empty. A comma in a query is rejected because the provider uses it to separate comparison terms.

ConfigLoader requires the configured SerpAPI environment variable even when AI is disabled. Store .env beside the YAML, or export the key in the shell. Use Config.model_validate for schema validation without credentials.

Retrieval fails

Check your SerpAPI account and the requested geography/date expression. The provider uses a 30-second request timeout by default. YAML exposes retries and backoff, not timeout. HTTP failures can be retried with exponential delays; retry_attempts: 0 requests one attempt. This library has no local cache. Malformed JSON and missing timeline data are errors. Retrying a request can use provider quota. Do not put credentials in issue reports or logs.

Calculations fail

Every returned date must contain each requested query exactly once. Non-finite, negative, malformed or missing interest values are invalid. All-zero totals make the share undefined; increasing the arithmetic tolerance cannot fix this.

Review the queries and raw response instead of imputing missing brands as zero. Missing whole dates and irregular interval spacing require analyst review. The library does not infer their cause or fill a calendar grid.

Narration is unavailable

Inspect run_metadata.json and analysis.log. Without a key, narration falls back to an automated summary. Provider failures and incomplete responses are counted; other successful sections can still be retained. Confirm that OPENAI_MODEL supports the request arguments. See AI narration.

Charts or slides are missing

The pipeline logs these failures and retains CSVs. Check directory permissions, available disk space and the reported exception. PowerPoint requires enabled narration and chart paths, even when the narration is an automated fallback. Use a fresh output directory to avoid confusing older files with current outputs.

Documentation is unavailable

The site is a separately deployed static build. See release and hosting. A working package does not imply the site has been uploaded. For support, contact info@griffin-mmm.com.