# 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.