# 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/Profile Directory Settings Symptom: - CLI parse errors saying prompt directory or profile directory is required. Likely cause: - Neither CLI flags nor config provide effective `prompt_dir` / `profile_dir`. Diagnostic step: - Run the failing command with explicit `--prompt-dir` and `--profile-dir` once to verify. Safe fix: - Set `prompt_dir` and `profile_dir` in config, or always pass both flags. 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 --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 --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)