Document Promptkit report generation
This commit is contained in:
@@ -1,271 +1,48 @@
|
||||
# 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.
|
||||
Keep failed workspace artifacts in place. When a RunID is available, start
|
||||
with `weatherreporter inspect metadata RUN_ID` and use the paths in its result.
|
||||
|
||||
## A command or configuration is rejected before work starts
|
||||
## Prompt inspection or credentials fail before collection
|
||||
|
||||
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.
|
||||
A prompt/version, contract, selected profile, unsupported direct-key profile,
|
||||
or required environment credential can fail before weather collection. Correct
|
||||
the configured `promptkit` profile or profile source, confirm the exact
|
||||
Promptkit asset is available, and supply any reported environment credential.
|
||||
Do not add provider keys to YAML. See [configuration](config.md).
|
||||
|
||||
Likely cause: The command does not accept that option for the requested report,
|
||||
or required command and configuration values are absent or malformed.
|
||||
## Preparation, capacity, or execution fails
|
||||
|
||||
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).
|
||||
A preparation failure occurs before provider work; an execution failure occurs
|
||||
after preparation. Both leave safe provenance and metadata when reached. A
|
||||
capacity error for one batch report does not retry that report or prevent later
|
||||
independent reports. Inspect the preparation or execution path, correct the
|
||||
profile/backend condition, and create a new run. See [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.
|
||||
Raw generated output may be saved but Markdown is not rendered when the JSON
|
||||
does not match the report schema. Correct the Promptkit prompt/profile behavior
|
||||
or the matching schema and validator in source control; do not edit raw output
|
||||
to treat it as validated. See [templates](templates.md).
|
||||
|
||||
Likely cause: Returned text does not meet the report's validation rules.
|
||||
## Debug capture fails
|
||||
|
||||
Diagnostic: Use `weatherreporter inspect metadata RUN_ID` to find the saved raw
|
||||
generated-text artifact, and inspect it alongside the reported validation
|
||||
message.
|
||||
`--llm-debug-dir` must be an absolute secure directory outside workspace state.
|
||||
A debug-write failure stops the affected report to avoid continuing without the
|
||||
requested diagnostic. Repair the named path's ownership or permissions, then
|
||||
rerun. Treat capture files as sensitive. See [operations](operations.md).
|
||||
|
||||
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.
|
||||
## Weather, state, output, or notification fails
|
||||
|
||||
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).
|
||||
Collection errors precede planning. Later filesystem, output-copy, template,
|
||||
or Distributor errors retain the reached safe paths in the summary. Repair only
|
||||
the reported endpoint or path, leave successful managed reports intact, and
|
||||
rerun the affected report or batch. A batch notification is intentionally
|
||||
skipped when any report item fails.
|
||||
|
||||
## 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).
|
||||
Secret files must be regular non-symlink files directly beneath
|
||||
`secrets.directory` with valid environment-variable basenames. Correct the
|
||||
reported file or directory without placing secret values in YAML.
|
||||
|
||||
Reference in New Issue
Block a user