# Troubleshooting

This guide lists common implemented failure modes and safe fixes.

Canonical references:

- [CLI reference](cli.md)
- [Configuration reference](config.md)
- [HTTP API reference](api.md)
- [Operations guide](operations.md)

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

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

Relevant links: [Configuration reference](config.md), [CLI reference](cli.md)

## 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](config.md), [CLI reference](cli.md)

## 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](cli.md)

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

```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/version.
- Fix prompt YAML and referenced `content_file` paths.
- Fix output contract fields.

Relevant links: [Configuration reference](config.md), [CLI reference](cli.md)

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

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

Relevant links: [Configuration reference](config.md), [CLI reference](cli.md)

## 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](api.md), [Configuration reference](config.md)

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

```bash
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](config.md), [Operations guide](operations.md)

## 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](config.md), [CLI reference](cli.md)

## 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](operations.md), [Configuration reference](config.md)

## 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](operations.md), [HTTP API reference](api.md)

## 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](config.md), [Operations guide](operations.md)

## 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](api.md)

## 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](api.md), [Operations guide](operations.md)

## 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](api.md)