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, module snapshot, 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 within the same distributor token and pipeline. By default the bundle ID is a stable report-stream identity and the idempotency key appends RunID.

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

Also inspect the notification artifact linked from metadata. It records the rendered pipeline ID, bundle ID, idempotency key, upload result, distributor run status, status error, and raw run report JSON when available.

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, pipeline ID, bundle ID, idempotency key, source file, or one of the rendered bundle paths.

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

If the upload was accepted but destination output did not change, inspect the notification artifact's runStatus.report. Distributor actions such as replace_older, skip_same, skip_destination_newer, or failed explain how the destination handled the uploaded bundle.

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.