76 lines
3.8 KiB
Markdown
76 lines
3.8 KiB
Markdown
# Troubleshooting
|
|
|
|
Start with the command's classified error. When content-rich prompt diagnostics
|
|
are needed, enable a new run with `--llm-debug-dir` and handle the resulting
|
|
secure capture as sensitive. Current-version workspace receipts can provide
|
|
additional context when present, but are transitional state rather than a
|
|
long-term troubleshooting interface.
|
|
|
|
## 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.
|
|
|
|
Current-version preparation and execution receipts may retain the selected
|
|
profile ID and effective backend/model, but not an endpoint or credential.
|
|
Use them only as supplemental context after the active command error or an
|
|
explicit secure debug capture. 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. A capacity error for one batch report does not retry that
|
|
report or prevent later independent reports. Correct the profile or backend
|
|
condition identified by the bounded command error, then create a new run.
|
|
Use explicit secure debug capture only when additional content-rich diagnostics
|
|
are necessary. 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.
|