49 lines
2.3 KiB
Markdown
49 lines
2.3 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).
|
|
|
|
## 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.
|