362 lines
8.8 KiB
Markdown
362 lines
8.8 KiB
Markdown
# 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)
|