weatherreporter/docs/troubleshooting.md

Troubleshooting

Use the error from the command together with the run artifacts when a run ID is available. Start with inspect metadata to identify the report and artifact paths, then use the narrower inspection command named below. Do not remove a workspace to diagnose a failure: it contains the evidence needed to correct it safely.

A command or configuration is rejected before work starts

Symptom: The command exits before it creates a run, with an unknown-flag, missing-argument, invalid date or time bound, invalid timezone, or weather_api.base_url message.

Likely cause: The command does not accept that option for the requested report, or required command and configuration values are absent or malformed.

Diagnostic: Compare the command with generate and run and review the configured value named in the error. generate daily requires --date.

Safe fix: Correct only the reported option or configuration value. Use an absolute Weather API URL and a valid IANA timezone; do not change unrelated workspace data.

See also: Configuration and Weather API integration.

Weather data cannot be collected

Symptom: A generation command fails while fetching weather data, or reports hourly forecast data is missing or contains no periods.

Likely cause: The Weather API is unavailable, its configured endpoint or credentials are unsuitable, or the response lacks the hourly forecast required by the selected report.

Diagnostic: Check the service status and the configured base URL, then retry the same report. If a run ID was produced, run weatherreporter inspect sources RUN_ID to see the recorded source result.

Safe fix: Restore access to the configured Weather API or choose a reporting period supported by the returned forecast. Do not invent missing hourly values in local artifacts.

See also: Configuration and Weather API integration.

Optional source warnings appear

Symptom: The report succeeds but its output says that a source supplied a warning or degraded result.

Likely cause: An optional source did not return usable data; mandatory weather collection still completed.

Diagnostic: Run weatherreporter inspect sources RUN_ID and identify the source and warning recorded for that run.

Safe fix: Correct the affected source configuration or service issue, then generate a new report if the missing optional information is needed. Keep the existing run for comparison.

See also: Inspecting a run and Operations.

Scriptorium cannot be prepared

Symptom: The report fails with a fragment such as run scriptorium render, or the Scriptorium executable cannot be started.

Likely cause: The configured executable, profile, prompt, or its local runtime environment is unavailable to Weatherreporter.

Diagnostic: Confirm that the configured executable can be run by the same user and inspect weatherreporter inspect metadata RUN_ID when a run ID is shown.

Safe fix: Repair the executable path or the Scriptorium configuration and retry the report. Do not edit generated artifacts to bypass preparation.

See also: Configuration and Operations.

Scriptorium preflight fails

Symptom: A Scriptorium-backed report stops before text generation, often with a scriptorium render exited with code fragment.

Likely cause: Scriptorium rejected the render request, prompt, profile, or data package before it could run the report.

Diagnostic: Inspect the run metadata and the saved preflight artifact path it references. Compare the reported Scriptorium diagnostic with its configuration.

Safe fix: Correct the reported Scriptorium input or configuration, then create a new run. Preserve the failed preflight artifact for support or comparison.

See also: Inspecting a run and Operations.

Scriptorium report execution fails

Symptom: Preparation succeeded, but generation stops with a scriptorium run exited with code fragment.

Likely cause: The Scriptorium run failed after preflight, for example because its prompt execution or runtime dependency failed.

Diagnostic: Inspect the run metadata and preflight artifact, then review the exit diagnostic from the command. This distinguishes a run failure from a preflight failure.

Safe fix: Correct the Scriptorium issue identified by that diagnostic and run the report again; leave the failed run artifacts in place.

See also: Operations.

Generated text fails validation

Symptom: A generated-text report fails after Scriptorium returns text, with a message about generated text or required report content.

Likely cause: Returned text does not meet the report's validation rules.

Diagnostic: Use weatherreporter inspect metadata RUN_ID to find the saved raw generated-text artifact, and inspect it alongside the reported validation message.

Safe fix: Correct the upstream prompt or generation configuration that caused the invalid output, then create a new run. Do not hand-edit saved raw text and present it as a validated report.

See also: Operations.

Report template rendering fails

Symptom: Scriptorium output is available, but the report fails while building the final Markdown document.

Likely cause: The selected report template or the render context is incompatible with the generated or collected data.

Diagnostic: Inspect the metadata, generated-text result, and render-context artifacts for the run. Note the template or missing-field fragment in the error rather than relying on a complete error string.

Safe fix: Correct the template or its supported inputs in source control, test the change, and create a new report. Do not alter the saved context merely to make one historical run render.

See also: Operations.

A report fails after artifacts are saved

Symptom: A generation command reports an error after showing a run ID, such as an error writing the managed report, copying --out, saving metadata, or notifying Distributor.

Likely cause: A local filesystem permission or path problem, an unavailable destination for --out, or a later report-delivery failure occurred after earlier steps succeeded.

Diagnostic: Run weatherreporter inspect metadata RUN_ID and check the exact path and operation named in the error. For an --out failure, verify only the specified destination directory and filename.

Safe fix: Repair access to that exact path or disable the optional delivery step only when appropriate, then generate a new report. Keep the existing managed artifacts untouched.

See also: Operations and Distributor integration.

A batch has partial report failures

Symptom: run morning or run evening returns nonzero and reports both succeeded and failed report items.

Likely cause: A report-level collection, generation, rendering, or local output failure affected one or more planned reports; the remaining reports continue independently.

Diagnostic: Read the per-report status lines, then inspect the run ID for each failed item with weatherreporter inspect metadata RUN_ID.

Safe fix: Correct the specific failure and rerun the batch or affected report. Do not delete successful reports simply because another item failed.

See also: Batch commands and Operations.

A batch upload is skipped

Symptom: The batch result says Distributor notification was skipped because one or more reports failed.

Likely cause: Batch notification intentionally runs only after every planned report succeeds.

Diagnostic: Review the failed report items and their metadata; a skipped batch notification is expected while any item is failed.

Safe fix: Resolve the report failures and rerun the batch. Do not upload a partial bundle by manually reusing batch artifacts.

See also: Batch commands and Operations.

Distributor notification fails

Symptom: A completed report or otherwise successful batch reports a Distributor error, including a rejected upload, source or idempotency conflict, or service unavailability.

Likely cause: Distributor rejected the request identity or bundle, required credentials are unavailable, or the remote service cannot be reached.

Diagnostic: Inspect the report metadata or batch result for the notification artifact and the error fragment. Verify the configured Distributor endpoint and request identity without exposing credentials.

Safe fix: Resolve the reported remote conflict, configuration, or availability issue and create a new report or rerun the batch. Do not modify recorded bundle or idempotency artifacts to force an upload.

See also: Configuration, Distributor integration, and Operations.

Secrets cannot be loaded

Symptom: Startup reports read secrets directory, secret file, or a token environment-variable error before the affected service can be used.

Likely cause: The configured secrets directory cannot be read, contains a non-regular file, or does not supply the environment variable required by an enabled integration.

Diagnostic: Check the configured secrets directory path, ownership, and that each intended secret is a regular file. Confirm the variable name from configuration only; never print or paste its value.

Safe fix: Correct permissions, file type, or the missing secret file, then retry. Keep secret values out of commands, logs, tickets, and artifacts.

See also: Configuration and Operations.

A run ID or saved state cannot be found

Symptom: An inspection command reports that metadata for a run ID was not found, or a report cannot use a prior snapshot.

Likely cause: The run ID is wrong, the configured workspace is different from the one that created the run, or no compatible prior snapshot exists.

Diagnostic: Use weatherreporter inspect reports to list available reports in the current workspace, then copy the run ID from that output. Confirm the workspace configuration before retrying a prior-snapshot operation.

Safe fix: Use an existing run ID and its original workspace, or generate a new compatible report when no prior snapshot is available. Do not fabricate state files or run IDs.

See also: Inspecting a run and Operations.

Workspace paths cannot be read or written

Symptom: Startup or report persistence reports a workspace-path, permission, or "must be relative to workspace root" error.

Likely cause: A configured artifact directory escapes the workspace, or the current user lacks access to the specific workspace location.

Diagnostic: Check the named configuration path against the configured workspace root and inspect ownership and permissions of that exact directory.

Safe fix: Set the path to a location within the workspace or repair access to the named directory, then rerun. Do not remove the workspace or broadly relax permissions.

See also: Configuration and Operations.