341 lines
11 KiB
Markdown
341 lines
11 KiB
Markdown
# 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, module snapshot, 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).
|