# 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). ## 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](config.md). ## 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](config.md), [Operations guide](operations.md). ## 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](operations.md), [Distributor adapter internals](internal/distributor-adapter.md). ## 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](config.md), [Operations guide](operations.md), [Distributor adapter internals](internal/distributor-adapter.md). ## 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](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).