# Weatherreporter Troubleshooting This guide lists recurring failures with likely causes, diagnostics, and safe fixes. See [CLI reference](cli.md), [Configuration reference](config.md), and [Operations guide](operations.md) for normal usage. ## `weather_api.base_url is required` Symptom: a generation command fails before fetching weather data. Likely cause: no Weather API base URL is configured. Diagnostic: ```sh weatherreporter generate daily --config ./config.yml --date 2026-05-29 ``` Safe fix: add `weather_api.base_url` to the config file, or pass the intended config path with `--config`. Relevant docs: [Configuration reference](config.md). ## `weather_api.base_url must be an absolute URL` Symptom: config loading fails with a base URL validation error. Likely cause: `weather_api.base_url` is missing a scheme or host. Diagnostic: inspect the configured value in the file passed to `--config`. Safe fix: use an absolute URL such as `https://weather.api.example.com/`. Relevant docs: [Configuration reference](config.md). ## Invalid Timezone Symptom: config loading fails with `weather_api.timezone` context, or a CLI timezone override fails. Likely cause: `weather_api.timezone` or `--tz` is not recognized. Diagnostic: ```sh weatherreporter generate daily --tz America/Chicago --date 2026-05-29 ``` Safe fix: use an accepted timezone value, such as an IANA timezone name, `Chicago`, `Stl`, a US timezone abbreviation, or a UTC offset. Relevant docs: [Configuration reference](config.md). ## Storm Command Rejects Time Bounds Symptom: `generate storm` fails with `requires --start`, `requires --end`, or `requires --end after --start`. Likely cause: the manual event window is missing or invalid. Diagnostic: ```sh weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00 ``` Safe fix: provide both bounds. Use `YYYY-MM-DDTHH:MM` in the configured timezone, or RFC3339 timestamps with explicit offsets. Relevant docs: [CLI reference](cli.md). ## Weather API Fetch Fails Symptom: generation fails with `fetch /...`, an HTTP status, or request context. Likely cause: the configured Weather API endpoint is unreachable, returned a non-2xx response, or returned an invalid response envelope. Diagnostic: ```sh weatherreporter generate daily --config ./config.yml --date 2026-05-29 ``` Safe fix: verify `weather_api.base_url`, network access, and the Weather API service response. The adapter fetches `/observations`, `/conditions/current`, `/forecast/hourly`, `/forecast/narrative`, `/alerts/active`, and `/discussion`. Relevant docs: [Configuration reference](config.md). ## Hourly Forecast Is Missing Symptom: generation fails with hourly forecast context, such as missing hourly data or an hourly forecast containing no periods. Likely cause: hourly forecast data is required for generated reports. Diagnostic: check the Weather API response for `/forecast/hourly`. Safe fix: restore hourly forecast data at the Weather API. Missing-source policy cannot make hourly optional. Relevant docs: [Configuration reference](config.md), [Operations guide](operations.md). ## Source Warnings Appear Symptom: generation succeeds, but metadata or `inspect sources` shows source warnings. Likely cause: an optional source was missing or malformed under a warning missing-source policy. Diagnostic: ```sh weatherreporter inspect sources RUN_ID weatherreporter inspect metadata RUN_ID ``` Safe fix: inspect the warning `source`, `code`, `message`, and `endpoint`. Fix the upstream optional source, or intentionally change the relevant `missing_source` policy. Relevant docs: [Configuration reference](config.md), [Operations guide](operations.md). ## `scriptorium` Is Not Found Or Cannot Start Symptom: generation fails with `run scriptorium render` or `run scriptorium` and an executable or OS error. Likely cause: the configured Scriptorium binary is unavailable or not executable. Diagnostic: check `scriptorium.binary` in config and run the same binary outside `weatherreporter`. Safe fix: install Scriptorium, update `scriptorium.binary`, or fix executable permissions. Relevant docs: [Configuration reference](config.md), [Scriptorium integration](integrations/scriptorium.md). ## Render Preflight Fails Symptom: generation fails with `scriptorium render exited with code ...`. Likely cause: Scriptorium rejected the prompt, config, profile, or `data_package` input before report generation. Diagnostic: ```sh weatherreporter inspect metadata RUN_ID weatherreporter inspect data-package RUN_ID ``` Then read the preflight path from metadata. It contains captured stdout, stderr, exit code, and command. Safe fix: fix the Scriptorium configuration, prompt ID, profile, or data package input indicated by stderr. Relevant docs: [Operations guide](operations.md), [Scriptorium integration](integrations/scriptorium.md). ## Scriptorium Run Fails Symptom: generation fails with `scriptorium run exited with code ...`. Likely cause: Scriptorium failed during report generation or validation. Diagnostic: ```sh weatherreporter inspect metadata RUN_ID weatherreporter inspect data-package RUN_ID ``` If metadata includes a rendered report path, inspect that report as well. A nonzero run can still leave a managed report artifact. Safe fix: use the captured stderr and data package to fix the Scriptorium prompt, profile, model configuration, or validation issue. Relevant docs: [Operations guide](operations.md), [Scriptorium integration](integrations/scriptorium.md). ## Batch Command Returns Nonzero Symptom: `run morning` or `run evening` returns nonzero. Likely cause: at least one report in the batch failed. Diagnostic: inspect stdout for the JSON summary and stderr for compact status lines. Safe fix: use the failed report's artifact paths from the summary, then inspect metadata, sources, briefing, and data package for that RunID. Relevant docs: [CLI reference](cli.md), [Operations guide](operations.md). ## Unknown RunID Symptom: an inspect command fails with `metadata for run id ... was not found`. Likely cause: the RunID is mistyped or the command is reading a different workspace. Diagnostic: ```sh weatherreporter inspect reports --config ./config.yml --limit 20 ``` Safe fix: copy a RunID from `inspect reports`, or use the same `--config` and workspace that generated the report. Relevant docs: [Operations guide](operations.md). ## Workspace Path Error Symptom: startup or inspection fails with workspace path validation or filesystem read/write context. Likely cause: a workspace subdirectory is absolute, escapes `workspace.root`, or the process cannot read or write the configured path. Diagnostic: review `workspace.root`, `workspace.snapshots_dir`, `workspace.reports_dir`, `workspace.data_packages_dir`, and `workspace.preflight_dir`. Safe fix: keep workspace subdirectories relative to `workspace.root`, and grant the process appropriate filesystem permissions. Relevant docs: [Configuration reference](config.md), [Operations guide](operations.md).