3.8 KiB
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.
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.
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.
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.
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.
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.