scriptorium/docs/troubleshooting.md

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