# Troubleshooting Use the error from the command together with the run artifacts when a run ID is available. Start with [`inspect metadata`](cli.md#inspection-commands) 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`](cli.md#commands-and-usage) 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](config.md) and [Weather API integration](integrations/weatherapi.md). ## 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](config.md) and [Weather API integration](integrations/weatherapi.md). ## 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](cli.md#inspection-commands) and [Operations](operations.md). ## 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](config.md) and [Operations](operations.md). ## 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](cli.md#inspection-commands) and [Operations](operations.md). ## 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](operations.md). ## 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](operations.md). ## 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](operations.md). ## 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](operations.md) and [Distributor integration](integrations/distributor/pkg-upload.md). ## 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](cli.md#commands-and-usage) and [Operations](operations.md). ## 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](cli.md#commands-and-usage) and [Operations](operations.md). ## 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](config.md), [Distributor integration](integrations/distributor/pkg-upload.md), and [Operations](operations.md). ## 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](config.md) and [Operations](operations.md). ## 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](cli.md#inspection-commands) and [Operations](operations.md). ## 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](config.md) and [Operations](operations.md).