weatherreporter/docs/troubleshooting.md

Weatherreporter Troubleshooting

This guide lists recurring failures with likely causes, diagnostics, and safe fixes. See CLI reference, Configuration reference, and Operations guide 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:

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.

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.

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:

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.

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:

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.

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:

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.

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, Operations guide.

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:

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, Operations guide.

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, Scriptorium integration.

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:

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, Scriptorium integration.

Scriptorium Run Fails

Symptom: generation fails with scriptorium run exited with code ....

Likely cause: Scriptorium failed during report generation or validation.

Diagnostic:

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, Scriptorium integration.

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, Operations guide.

Invalid Secrets Directory

Symptom: config loading fails with read secrets directory, secret file, or environment variable name context.

Likely cause: secrets.directory points to a missing directory or contains an invalid entry. Secret entries must be regular files directly under the configured directory, and file basenames must match [A-Za-z_][A-Za-z0-9_]*.

Diagnostic: list the configured directory and inspect entry names and file types. Do not print secret file contents.

Safe fix: create the directory, remove subdirectories or symlinks, fix invalid filenames, and ensure the weatherreporter process can read each secret file.

Relevant docs: Configuration reference.

Distributor Token Is Missing

Symptom: notification fails with a message that the distributor token environment variable is not set.

Likely cause: notify.distributor.enabled is true, but the environment variable named by notify.distributor.token_env was not populated directly or through secrets.directory.

Diagnostic: check notify.distributor.token_env, then verify a matching secret file exists under secrets.directory or that the process environment includes the variable. Do not print the token value.

Safe fix: create a readable secret file whose basename matches token_env, or set the environment variable through the service manager.

Relevant docs: Configuration reference, Operations guide.

Distributor Upload Conflict

Symptom: notification fails with idempotency conflict context.

Likely cause: the same idempotency key was reused for different bundle content. By default the key derives from bundle ID, which includes location ID, report ID, and RunID.

Diagnostic: inspect the failed batch JSON or stderr line for bundle and idempotency context. Compare the configured templates with the report RunID and report path.

Safe fix: keep idempotency templates stable for retries of the same generated report, but do not reuse the same rendered key for different generated report content.

Relevant docs: Operations guide, Distributor adapter internals.

Distributor Upload Rejected

Symptom: notification fails with distributor upload rejection, HTTP status, or bundle validation context.

Likely cause: the distributor endpoint rejected the token, bundle ID, idempotency key, source file, or bundle path.

Diagnostic: inspect stdout JSON or stderr status lines for notificationError. Confirm notify.distributor.endpoint, notify.distributor.report_path_template, and token configuration. Token values are redacted from weatherreporter errors.

Safe fix: fix the endpoint, token, templates, or distributor-side upload configuration. The weatherreporter upload source is the managed Markdown report, not --out or --out-dir copies.

Relevant docs: Configuration reference, Operations guide, Distributor adapter internals.

Distributor Unavailable

Symptom: notification fails with network, timeout, or service unavailable context.

Likely cause: the configured distributor endpoint is unreachable, slow, or temporarily unavailable.

Diagnostic: check network access from the weatherreporter host to notify.distributor.endpoint. For batch runs, inspect which reports have notificationStatus: "failed".

Safe fix: restore distributor service availability and rerun the affected report or batch. Stable idempotency keys make retrying the same generated report safe unless the distributor reports a conflict.

Relevant docs: Operations guide.

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:

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.

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, Operations guide.