71 lines
3.5 KiB
Markdown
71 lines
3.5 KiB
Markdown
# Troubleshooting
|
|
|
|
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.
|
|
|
|
## Prompt inspection or credentials fail before collection
|
|
|
|
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).
|
|
|
|
## Local profile override is malformed or selects an unexpected model
|
|
|
|
`promptkit.profile_file` and `promptkit.profile_dir` supply complete profile
|
|
definitions. A same-ID definition replaces the embedded profile, and a malformed
|
|
matching definition fails before collection instead of falling back. Validate
|
|
the selected profile's YAML, ID, backend or endpoint, and model. If the model
|
|
is unexpected, first check the global `promptkit.profile` selection and then
|
|
look for a same-ID definition in the configured file or directory.
|
|
|
|
The preparation and execution receipts named by run metadata retain the
|
|
selected profile ID and effective backend/model for diagnosis, but not an
|
|
endpoint or credential. See the maintained
|
|
[local `weather-light` profile example](../examples/weather-light-local-profile.yml).
|
|
|
|
## Local model endpoint is unavailable
|
|
|
|
An endpoint-only `weather-light` override can pass preflight and still fail
|
|
during provider preparation or execution when the local server is unavailable
|
|
or does not accept the configured model. Start the local server, correct the
|
|
endpoint or model in the profile, and run the command again. Weatherreporter
|
|
does not probe endpoints or automatically use a remote profile instead.
|
|
|
|
## Preparation, capacity, or execution fails
|
|
|
|
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
|
|
|
|
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).
|
|
|
|
## Debug capture fails
|
|
|
|
`--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).
|
|
|
|
## Weather, state, output, or notification fails
|
|
|
|
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
|
|
|
|
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.
|