scriptorium/docs/troubleshooting.md

Troubleshooting

This guide lists common implemented failure modes and safe fixes.

Canonical references:

• CLI reference
• Configuration reference
• HTTP API reference
• Operations guide

Missing Or Invalid Config

Symptom:

• CLI error includes application config error, config file not found, invalid config YAML, or invalid config.

Likely cause:

• --config points to a missing file.
• YAML syntax is invalid.
• Config contains unknown fields or negative HTTP size limits.

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 the config path.
• Fix YAML syntax.
• Remove unknown fields.
• Keep raw secrets out of config.

Relevant links: Configuration reference, CLI reference

Missing Prompt Directory

Symptom:

• CLI parse error says the prompt directory is required.

Likely cause:

• Neither config nor CLI flags provide an effective prompt_dir.

Diagnostic step:

• Re-run once with explicit --prompt-dir.

Safe fix:

• Set prompt_dir in config or pass --prompt-dir.

Relevant links: Configuration reference, CLI reference

Unknown Flags

Symptom:

• CLI parse error for an unknown flag.

Likely cause:

• Typo.
• Flag is valid for another command.
• serve was given runtime model override flags.

Diagnostic step:

• Compare the command with the command-specific flag list.

Safe fix:

• Remove unsupported flags.
• Use run or render for runtime model overrides.

Relevant links: CLI reference

Prompt Load Failures

Symptom:

• CLI run/render fails during prompt loading.
• HTTP returns 404 prompt_not_found or 400 prompt_load_failed.

Likely cause:

• Prompt ID/version does not exist.
• Prompt YAML is invalid or has unknown fields.
• Prompt contract is invalid, such as missing messages, invalid output mode, bad content_file, or 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/version.
• Fix prompt YAML and referenced content_file paths.
• Fix output contract fields.

Relevant links: Configuration reference, CLI reference

Profile Load Failures

Symptom:

• CLI run/render fails during profile loading.
• HTTP returns 404 profile_not_found, 400 profile_load_failed, or 400 profile_required.

Likely cause:

• Profile ID does not exist.
• Request omitted profile and prompt has no default_profile.
• Profile YAML is invalid or has unknown fields.
• Profile contains raw api_key.

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 or prompt default_profile.
• Fix profile YAML and value ranges.
• Replace raw api_key with api_key_env.

Relevant links: Configuration reference, CLI reference

Input Artifact Failures

Symptom:

• CLI run/render fails while reading inputs.
• HTTP returns 400 artifact_read_failed, 400 artifact_not_allowed, or 413 artifact_too_large.

Likely cause:

• Input file path is missing or unreadable.
• HTTP input type is unsupported or missing required fields.
• HTTP file refs are disabled because no artifact root is configured.
• HTTP file path is lexically outside the artifact root.
• HTTP file input exceeds server.max_artifact_bytes.

Diagnostic step:

• Verify each input path exists and is readable by the process.
• For HTTP, verify input refs use file or inline.
• For HTTP file refs, verify the artifact root and compare file size to server.max_artifact_bytes.

Safe fix:

• Correct paths and permissions.
• Configure a narrow artifact root for HTTP file refs.
• Use relative paths under the artifact root or switch to inline.
• Increase server.max_artifact_bytes only for expected larger inputs.

Relevant links: HTTP API reference, Configuration reference

Missing API-Key Environment Variable

Symptom:

• CLI render/run fails with an API-key environment error.
• HTTP returns 400 api_key_env_missing.

Likely cause:

• Selected profile or runtime override sets api_key_env, but the environment variable is unset or empty.

Diagnostic step:

printenv SCRIPTORIUM_API_KEY

Safe fix:

• Set the required environment variable before starting the CLI command or HTTP service.
• Or use a profile that does not require provider API-key auth.

Relevant links: Configuration reference, Operations guide

Prompt Template Render Failures

Symptom:

• CLI render/run fails during prompt rendering.
• HTTP returns 400 prompt_render_failed.

Likely cause:

• Template references an input that was not supplied.
• Template syntax or variable reference is invalid.

Diagnostic step:

• Run render --format json with the same prompt, inputs, vars, and profile.

Safe fix:

• Align {{input "name"}} references with request input names.
• Fix template syntax and variable names.

Relevant links: Configuration reference, CLI reference

LLM Request Failures

Symptom:

• CLI run fails during generation.
• HTTP returns 502 llm_failed.

Likely cause:

• Endpoint is unreachable.
• Provider returns non-2xx.
• Request times out.
• Provider response is malformed.

Diagnostic step:

• Run render first to confirm pre-LLM preparation works.
• Check selected endpoint/model in prepared output.
• Check network/provider logs for timeout or non-2xx details.

Safe fix:

• Correct endpoint/model/profile settings.
• Adjust timeout when appropriate.
• Resolve provider or network issue.

Relevant links: Operations guide, Configuration reference

Validation Failed

Symptom:

• CLI run exits 2.
• HTTP returns 200 OK with validation.status set to failed.

Likely cause:

• Generated output failed basic, json, or json_schema content validation.

Diagnostic step:

• Inspect validation errors in CLI stderr or the HTTP response.

Safe fix:

• Refine prompt instructions.
• Adjust schema or model/profile settings.
• Rerun after correction.

Relevant links: Operations guide, HTTP API reference

Validation Runtime Failure

Symptom:

• CLI run fails with validation runtime error.
• HTTP returns 500 validation_runtime_failed.

Likely cause:

• json_schema schema file is missing or unreadable.
• Schema JSON is invalid.

Diagnostic step:

• Verify schema_dir and prompt output.schema_path.
• Check schema file readability and JSON syntax.

Safe fix:

• Correct schema path or permissions.
• Fix schema JSON.
• Rerun.

Relevant links: Configuration reference, Operations guide

HTTP JSON Or Request Contract Errors

Symptom:

• HTTP returns 400 invalid_json or 400 invalid_request.

Likely cause:

• JSON body is malformed.
• Request has unknown fields or trailing JSON tokens.
• Required prompt_id or inputs is missing.
• Runtime override values are out of range.
• extra_params collides with reserved outbound fields.

Diagnostic step:

• Revalidate request JSON and compare fields with the API reference.

Safe fix:

• Send one JSON object with only supported fields.
• Include prompt_id and at least one input.
• Use valid model override ranges.
• Remove reserved extra_params keys.

Relevant links: HTTP API reference

HTTP Size Limit Errors

Symptom:

• HTTP returns 413 request_too_large, 413 artifact_too_large, or 413 response_too_large.

Likely cause:

• JSON request body exceeds server.max_request_bytes.
• HTTP file input exceeds server.max_artifact_bytes.
• Encoded JSON response exceeds server.max_response_bytes.

Diagnostic step:

• Compare request, file input, and expected response sizes with configured limits.

Safe fix:

• Use smaller inline inputs or switch to file inputs under the artifact root.
• Reduce generated output size.
• Omit include_raw_output.
• Increase limits only when the deployment expects larger payloads.

Relevant links: HTTP API reference, Operations guide

HTTP Route Or Method Errors

Symptom:

• HTTP returns 404 not_found or 405 method_not_allowed.

Likely cause:

• Path is not /v1/runs.
• Method on /v1/runs is not POST.

Diagnostic step:

• Check the request URL and method.

Safe fix:

• Send POST /v1/runs.

Relevant links: HTTP API reference