368 lines
8.5 KiB
Markdown
368 lines
8.5 KiB
Markdown
# Troubleshooting
|
|
|
|
This guide lists recurring implemented failure modes and safe fixes.
|
|
|
|
For command syntax, see [CLI reference](cli.md). For configuration and file formats, see [Configuration reference](config.md). For operational behavior, see [Operations guide](operations.md).
|
|
|
|
## Missing Or Invalid Config File
|
|
|
|
Symptom:
|
|
|
|
- CLI errors such as `application config error: config file not found` or `invalid config YAML`.
|
|
|
|
Likely cause:
|
|
|
|
- `--config` points to a missing file.
|
|
- Config YAML has syntax errors or unknown fields.
|
|
|
|
Diagnostic step:
|
|
|
|
```bash
|
|
go run ./cmd/scriptorium render --config /path/to/config.yml --prompt generic.markdown_summary --input transcript=./examples/fixtures/transcript.md --input glossary=./examples/fixtures/glossary.yml
|
|
```
|
|
|
|
Safe fix:
|
|
|
|
- Correct file path.
|
|
- Remove unknown fields.
|
|
- Fix YAML syntax.
|
|
- Keep secrets out of config.
|
|
|
|
Relevant links:
|
|
|
|
- [Configuration reference](config.md)
|
|
- [CLI reference](cli.md)
|
|
|
|
## Missing Prompt Directory Settings
|
|
|
|
Symptom:
|
|
|
|
- CLI parse errors saying prompt directory is required.
|
|
|
|
Likely cause:
|
|
|
|
- Neither CLI flags nor config provide an effective `prompt_dir`.
|
|
|
|
Diagnostic step:
|
|
|
|
- Run the failing command with explicit `--prompt-dir` once to verify.
|
|
|
|
Safe fix:
|
|
|
|
- Set `prompt_dir` in config, or always pass `--prompt-dir`.
|
|
|
|
Relevant links:
|
|
|
|
- [Configuration reference](config.md)
|
|
- [CLI reference](cli.md)
|
|
|
|
## Unknown Or Unsupported Flags
|
|
|
|
Symptom:
|
|
|
|
- CLI parse error for an unknown flag.
|
|
|
|
Likely cause:
|
|
|
|
- Typo or command mismatch (for example, `serve` with runtime model override flags).
|
|
|
|
Diagnostic step:
|
|
|
|
- Compare command against the command-specific flag list.
|
|
|
|
Safe fix:
|
|
|
|
- Remove unsupported flags.
|
|
- Use `run`/`render` for runtime model overrides.
|
|
|
|
Relevant links:
|
|
|
|
- [CLI reference](cli.md)
|
|
|
|
## Prompt Definition Load Failures
|
|
|
|
Symptom:
|
|
|
|
- CLI run/render error from prompt loading.
|
|
- HTTP `404 prompt_not_found` or `400 prompt_load_failed`.
|
|
|
|
Likely cause:
|
|
|
|
- Prompt ID not found.
|
|
- Invalid prompt YAML.
|
|
- Invalid prompt contract (for example bad validation mode, message content/content_file rule violation, missing schema path for `json_schema`).
|
|
|
|
Diagnostic step:
|
|
|
|
```bash
|
|
go run ./cmd/scriptorium render --config ./examples/config.yml --prompt <prompt-id> --input transcript=./examples/fixtures/transcript.md --input glossary=./examples/fixtures/glossary.yml --format json
|
|
```
|
|
|
|
Safe fix:
|
|
|
|
- Correct prompt ID.
|
|
- Fix prompt YAML and contract fields.
|
|
- Ensure referenced `content_file` paths exist.
|
|
|
|
Relevant links:
|
|
|
|
- [Configuration reference](config.md)
|
|
- [CLI reference](cli.md)
|
|
|
|
## Profile Definition Load Failures
|
|
|
|
Symptom:
|
|
|
|
- CLI run/render error from profile loading.
|
|
- HTTP `404 profile_not_found` or `400 profile_load_failed`.
|
|
|
|
Likely cause:
|
|
|
|
- Profile ID missing/not found.
|
|
- Invalid profile YAML.
|
|
- Invalid profile values.
|
|
- Raw `api_key` field present (rejected).
|
|
|
|
Diagnostic step:
|
|
|
|
```bash
|
|
go run ./cmd/scriptorium render --config ./examples/config.yml --prompt generic.markdown_summary --profile <profile-id> --input transcript=./examples/fixtures/transcript.md --input glossary=./examples/fixtures/glossary.yml
|
|
```
|
|
|
|
Safe fix:
|
|
|
|
- Correct profile ID.
|
|
- Fix profile YAML and value ranges.
|
|
- Replace `api_key` with `api_key_env`.
|
|
|
|
Relevant links:
|
|
|
|
- [Configuration reference](config.md)
|
|
- [CLI reference](cli.md)
|
|
|
|
## Input Artifact Read Failures
|
|
|
|
Symptom:
|
|
|
|
- CLI run/render error reading input artifacts.
|
|
- HTTP `400 artifact_read_failed`.
|
|
|
|
Likely cause:
|
|
|
|
- File path in input mapping does not exist or is unreadable.
|
|
- Unsupported artifact reference type in HTTP request.
|
|
|
|
Diagnostic step:
|
|
|
|
- Verify every mapped file path exists and is readable by the process.
|
|
- For HTTP, verify each input uses supported `type` values.
|
|
|
|
Safe fix:
|
|
|
|
- Correct file paths and permissions.
|
|
- Use supported input types (`file`, `inline`).
|
|
|
|
Relevant links:
|
|
|
|
- [CLI reference](cli.md)
|
|
- [Configuration reference](config.md)
|
|
|
|
## Prompt Template Render Failures
|
|
|
|
Symptom:
|
|
|
|
- CLI run/render error from prompt rendering.
|
|
- HTTP `400 prompt_render_failed`.
|
|
|
|
Likely cause:
|
|
|
|
- Template references missing input names.
|
|
- Template syntax or data reference issues.
|
|
|
|
Diagnostic step:
|
|
|
|
- Run `render --format json` with the same prompt, inputs, vars, and profile selection.
|
|
|
|
Safe fix:
|
|
|
|
- Align template `{{input "name"}}` references with actual input mappings.
|
|
- Fix template syntax and variable names.
|
|
|
|
Relevant links:
|
|
|
|
- [CLI reference](cli.md)
|
|
- [Configuration reference](config.md)
|
|
|
|
## Missing API-Key Environment Variable
|
|
|
|
Symptom:
|
|
|
|
- CLI run/render invalid request error about missing API-key environment variable.
|
|
- HTTP `400 api_key_env_missing`.
|
|
|
|
Likely cause:
|
|
|
|
- Selected profile or override sets `api_key_env`, but that environment variable is unset/empty.
|
|
|
|
Diagnostic step:
|
|
|
|
```bash
|
|
printenv SCRIPTORIUM_API_KEY
|
|
```
|
|
|
|
Safe fix:
|
|
|
|
- Set the required environment variable before invoking CLI/service.
|
|
- Or use a profile that does not require API key auth for the target endpoint.
|
|
|
|
Relevant links:
|
|
|
|
- [Configuration reference](config.md)
|
|
- [Operations guide](operations.md)
|
|
|
|
## LLM Request Failures
|
|
|
|
Symptom:
|
|
|
|
- CLI `run` fails with LLM generation errors.
|
|
- HTTP returns `502 llm_failed`.
|
|
|
|
Likely cause:
|
|
|
|
- Endpoint unreachable.
|
|
- Non-2xx response from provider.
|
|
- Timeout.
|
|
- Malformed provider response.
|
|
|
|
Diagnostic step:
|
|
|
|
- Confirm endpoint URL and model in selected profile/overrides.
|
|
- Retry with `render` first to confirm pre-LLM preparation works.
|
|
- Check provider/network logs for non-2xx responses and timeouts.
|
|
|
|
Safe fix:
|
|
|
|
- Correct endpoint/model settings.
|
|
- Adjust timeout if needed.
|
|
- Resolve provider-side or network issues.
|
|
|
|
Relevant links:
|
|
|
|
- [CLI reference](cli.md)
|
|
- [Configuration reference](config.md)
|
|
- [Operations guide](operations.md)
|
|
|
|
## Prompt Cache Misses Or No Cache Usage
|
|
|
|
Symptom:
|
|
|
|
- CLI run summary omits `cached_tokens` / `cache_write_tokens`.
|
|
- HTTP `metadata.usage.cached_tokens` and `metadata.usage.cache_write_tokens` are both `0`.
|
|
- Provider cost or latency does not improve after repeated similar runs.
|
|
|
|
Likely cause:
|
|
|
|
- The selected prompt has no `messages[].cache_control`.
|
|
- Dynamic per-run input appears before the cache-controlled message and changes the provider cache key.
|
|
- The provider does not support the serialized cache-control shape for the selected model.
|
|
- The provider imposes minimum token thresholds or cache-breakpoint limits.
|
|
|
|
Diagnostic step:
|
|
|
|
- Run `render --format json` and verify the intended rendered message includes `cache_control`.
|
|
- Confirm stable reusable context appears before the cache-controlled message, with dynamic input after it.
|
|
- Check provider docs/logs for model support, minimum token thresholds, and breakpoint limits.
|
|
|
|
Safe fix:
|
|
|
|
- Move stable reusable context before the cache-controlled message.
|
|
- Move highly dynamic input after the cache breakpoint.
|
|
- Keep `cache_control.type: ephemeral` and, when using `ttl`, set `ttl: 1h`.
|
|
- Use CLI cache counters or HTTP cache usage fields to verify cache reads/writes after rerunning.
|
|
|
|
Relevant links:
|
|
|
|
- [Configuration reference](config.md)
|
|
- [OpenAI-compatible chat integration](integrations/openai-compatible-chat.md)
|
|
|
|
## Validation Status Failed (`run` Exit 2 Or HTTP 200 With Failed Status)
|
|
|
|
Symptom:
|
|
|
|
- CLI exits with code `2`.
|
|
- HTTP returns `200`, but `validation.status` is `failed`.
|
|
|
|
Likely cause:
|
|
|
|
- Generated output failed `basic`, `json`, or `json_schema` content validation.
|
|
|
|
Diagnostic step:
|
|
|
|
- Inspect validation mode and validation errors in CLI summary/HTTP response.
|
|
|
|
Safe fix:
|
|
|
|
- Refine prompt constraints.
|
|
- Tighten schema or adjust model/profile settings.
|
|
- Rerun after correction.
|
|
|
|
Relevant links:
|
|
|
|
- [Configuration reference](config.md)
|
|
- [Operations guide](operations.md)
|
|
|
|
## Validation Runtime Failure
|
|
|
|
Symptom:
|
|
|
|
- CLI `run` fails with validation runtime error.
|
|
- HTTP returns `500 validation_runtime_failed`.
|
|
|
|
Likely cause:
|
|
|
|
- `json_schema` schema file missing/inaccessible.
|
|
- Invalid schema JSON document.
|
|
|
|
Diagnostic step:
|
|
|
|
- Verify `schema_dir` and `output.schema_path` resolution.
|
|
- Check schema file readability and valid JSON syntax.
|
|
|
|
Safe fix:
|
|
|
|
- Correct schema path.
|
|
- Fix schema JSON content.
|
|
- Rerun.
|
|
|
|
Relevant links:
|
|
|
|
- [Configuration reference](config.md)
|
|
- [Operations guide](operations.md)
|
|
|
|
## HTTP Request Parsing/Contract Errors
|
|
|
|
Symptom:
|
|
|
|
- HTTP `400 invalid_json` or `400 invalid_request`.
|
|
|
|
Likely cause:
|
|
|
|
- Malformed JSON body.
|
|
- Unknown JSON fields.
|
|
- Missing required `prompt_id` or `inputs`.
|
|
|
|
Diagnostic step:
|
|
|
|
- Revalidate request JSON.
|
|
- Confirm required request fields are present.
|
|
|
|
Safe fix:
|
|
|
|
- Send valid JSON with only supported fields.
|
|
- Ensure `prompt_id` and at least one input mapping are included.
|
|
|
|
Relevant links:
|
|
|
|
- [Operations guide](operations.md)
|
|
- [CLI reference](cli.md)
|