scriptorium/docs/troubleshooting.md

Troubleshooting

This guide lists recurring implemented failure modes and safe fixes.

For command syntax, see CLI reference. For configuration and file formats, see Configuration reference. For operational behavior, see Operations guide.

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:

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
• CLI reference

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
• CLI reference

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

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:

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
• CLI reference

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:

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
• CLI reference

Input Artifact Read Failures

Symptom:

• CLI run/render error reading input artifacts.
• HTTP 400 artifact_read_failed.
• HTTP 400 artifact_not_allowed.

Likely cause:

• File path in input mapping does not exist or is unreadable.
• Unsupported artifact reference type in HTTP request.
• HTTP file input references are disabled because no artifact root is configured.
• HTTP file input path escapes the configured artifact root.

Diagnostic step:

• Verify every mapped file path exists and is readable by the process.
• For HTTP, verify each input uses supported type values.
• For HTTP file inputs, verify server.artifact_root or serve --artifact-root is configured and the requested path stays inside that root.

Safe fix:

• Correct file paths and permissions.
• Use supported input types (file, inline).
• Configure a narrow HTTP artifact root when HTTP file inputs are required.
• Use relative paths under the artifact root, or switch to inline inputs.

Relevant links:

• CLI reference
• Configuration reference
• HTTP API integration

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
• Configuration reference

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:

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
• Operations guide

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
• Configuration reference
• Operations guide

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
• OpenAI-compatible chat integration

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
• Operations guide

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
• Operations guide

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
• CLI reference