Clarify HTTP operations documentation
This commit is contained in:
@@ -1,19 +1,25 @@
|
||||
# Troubleshooting
|
||||
|
||||
This guide lists recurring implemented failure modes and safe fixes.
|
||||
This guide lists common 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).
|
||||
Canonical references:
|
||||
|
||||
## Missing Or Invalid Config File
|
||||
- [CLI reference](cli.md)
|
||||
- [Configuration reference](config.md)
|
||||
- [HTTP API reference](api.md)
|
||||
- [Operations guide](operations.md)
|
||||
|
||||
## Missing Or Invalid Config
|
||||
|
||||
Symptom:
|
||||
|
||||
- CLI errors such as `application config error: config file not found` or `invalid config YAML`.
|
||||
- CLI error includes `application config error`, `config file not found`, `invalid config YAML`, or `invalid config`.
|
||||
|
||||
Likely cause:
|
||||
|
||||
- `--config` points to a missing file.
|
||||
- Config YAML has syntax errors or unknown fields.
|
||||
- YAML syntax is invalid.
|
||||
- Config contains unknown fields or negative HTTP size limits.
|
||||
|
||||
Diagnostic step:
|
||||
|
||||
@@ -23,40 +29,34 @@ go run ./cmd/scriptorium render --config /path/to/config.yml --prompt generic.ma
|
||||
|
||||
Safe fix:
|
||||
|
||||
- Correct file path.
|
||||
- Remove unknown fields.
|
||||
- Correct the config path.
|
||||
- Fix YAML syntax.
|
||||
- Keep secrets out of config.
|
||||
- Remove unknown fields.
|
||||
- Keep raw secrets out of config.
|
||||
|
||||
Relevant links:
|
||||
Relevant links: [Configuration reference](config.md), [CLI reference](cli.md)
|
||||
|
||||
- [Configuration reference](config.md)
|
||||
- [CLI reference](cli.md)
|
||||
|
||||
## Missing Prompt Directory Settings
|
||||
## Missing Prompt Directory
|
||||
|
||||
Symptom:
|
||||
|
||||
- CLI parse errors saying prompt directory is required.
|
||||
- CLI parse error says the prompt directory is required.
|
||||
|
||||
Likely cause:
|
||||
|
||||
- Neither CLI flags nor config provide an effective `prompt_dir`.
|
||||
- Neither config nor CLI flags provide an effective `prompt_dir`.
|
||||
|
||||
Diagnostic step:
|
||||
|
||||
- Run the failing command with explicit `--prompt-dir` once to verify.
|
||||
- Re-run once with explicit `--prompt-dir`.
|
||||
|
||||
Safe fix:
|
||||
|
||||
- Set `prompt_dir` in config, or always pass `--prompt-dir`.
|
||||
- Set `prompt_dir` in config or pass `--prompt-dir`.
|
||||
|
||||
Relevant links:
|
||||
Relevant links: [Configuration reference](config.md), [CLI reference](cli.md)
|
||||
|
||||
- [Configuration reference](config.md)
|
||||
- [CLI reference](cli.md)
|
||||
|
||||
## Unknown Or Unsupported Flags
|
||||
## Unknown Flags
|
||||
|
||||
Symptom:
|
||||
|
||||
@@ -64,33 +64,33 @@ Symptom:
|
||||
|
||||
Likely cause:
|
||||
|
||||
- Typo or command mismatch (for example, `serve` with runtime model override flags).
|
||||
- Typo.
|
||||
- Flag is valid for another command.
|
||||
- `serve` was given runtime model override flags.
|
||||
|
||||
Diagnostic step:
|
||||
|
||||
- Compare command against the command-specific flag list.
|
||||
- Compare the command with the command-specific flag list.
|
||||
|
||||
Safe fix:
|
||||
|
||||
- Remove unsupported flags.
|
||||
- Use `run`/`render` for runtime model overrides.
|
||||
- Use `run` or `render` for runtime model overrides.
|
||||
|
||||
Relevant links:
|
||||
Relevant links: [CLI reference](cli.md)
|
||||
|
||||
- [CLI reference](cli.md)
|
||||
|
||||
## Prompt Definition Load Failures
|
||||
## Prompt Load Failures
|
||||
|
||||
Symptom:
|
||||
|
||||
- CLI run/render error from prompt loading.
|
||||
- HTTP `404 prompt_not_found` or `400 prompt_load_failed`.
|
||||
- CLI run/render fails during prompt loading.
|
||||
- HTTP returns `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`).
|
||||
- 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:
|
||||
|
||||
@@ -100,28 +100,25 @@ go run ./cmd/scriptorium render --config ./examples/config.yml --prompt <prompt-
|
||||
|
||||
Safe fix:
|
||||
|
||||
- Correct prompt ID.
|
||||
- Fix prompt YAML and contract fields.
|
||||
- Ensure referenced `content_file` paths exist.
|
||||
- Correct prompt ID/version.
|
||||
- Fix prompt YAML and referenced `content_file` paths.
|
||||
- Fix output contract fields.
|
||||
|
||||
Relevant links:
|
||||
Relevant links: [Configuration reference](config.md), [CLI reference](cli.md)
|
||||
|
||||
- [Configuration reference](config.md)
|
||||
- [CLI reference](cli.md)
|
||||
|
||||
## Profile Definition Load Failures
|
||||
## Profile Load Failures
|
||||
|
||||
Symptom:
|
||||
|
||||
- CLI run/render error from profile loading.
|
||||
- HTTP `404 profile_not_found` or `400 profile_load_failed`.
|
||||
- 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 missing/not found.
|
||||
- Invalid profile YAML.
|
||||
- Invalid profile values.
|
||||
- Raw `api_key` field present (rejected).
|
||||
- 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:
|
||||
|
||||
@@ -131,89 +128,52 @@ go run ./cmd/scriptorium render --config ./examples/config.yml --prompt generic.
|
||||
|
||||
Safe fix:
|
||||
|
||||
- Correct profile ID.
|
||||
- Correct profile ID or prompt `default_profile`.
|
||||
- Fix profile YAML and value ranges.
|
||||
- Replace `api_key` with `api_key_env`.
|
||||
- Replace raw `api_key` with `api_key_env`.
|
||||
|
||||
Relevant links:
|
||||
Relevant links: [Configuration reference](config.md), [CLI reference](cli.md)
|
||||
|
||||
- [Configuration reference](config.md)
|
||||
- [CLI reference](cli.md)
|
||||
|
||||
## Input Artifact Read Failures
|
||||
## Input Artifact Failures
|
||||
|
||||
Symptom:
|
||||
|
||||
- CLI run/render error reading input artifacts.
|
||||
- HTTP `400 artifact_read_failed`.
|
||||
- HTTP `400 artifact_not_allowed`.
|
||||
- HTTP `413 artifact_too_large`.
|
||||
- CLI run/render fails while reading inputs.
|
||||
- HTTP returns `400 artifact_read_failed`, `400 artifact_not_allowed`, or `413 artifact_too_large`.
|
||||
|
||||
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.
|
||||
- HTTP `file` input artifact exceeds `server.max_artifact_bytes`.
|
||||
- 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 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.
|
||||
- For HTTP `file` inputs, compare file size to `server.max_artifact_bytes`.
|
||||
- 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 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.
|
||||
- Increase `server.max_artifact_bytes` only when the deployment expects larger file inputs.
|
||||
- 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:
|
||||
|
||||
- [CLI reference](cli.md)
|
||||
- [Configuration reference](config.md)
|
||||
- [HTTP API reference](api.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)
|
||||
Relevant links: [HTTP API reference](api.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`.
|
||||
- CLI render/run fails with an API-key environment error.
|
||||
- HTTP returns `400 api_key_env_missing`.
|
||||
|
||||
Likely cause:
|
||||
|
||||
- Selected profile or override sets `api_key_env`, but that environment variable is unset/empty.
|
||||
- Selected profile or runtime override sets `api_key_env`, but the environment variable is unset or empty.
|
||||
|
||||
Diagnostic step:
|
||||
|
||||
@@ -223,85 +183,68 @@ 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.
|
||||
- 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:
|
||||
Relevant links: [Configuration reference](config.md), [Operations guide](operations.md)
|
||||
|
||||
- [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 with LLM generation errors.
|
||||
- CLI `run` fails during generation.
|
||||
- HTTP returns `502 llm_failed`.
|
||||
|
||||
Likely cause:
|
||||
|
||||
- Endpoint unreachable.
|
||||
- Non-2xx response from provider.
|
||||
- Timeout.
|
||||
- Malformed provider response.
|
||||
- Endpoint is unreachable.
|
||||
- Provider returns non-2xx.
|
||||
- Request times out.
|
||||
- Provider response is malformed.
|
||||
|
||||
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.
|
||||
- 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 settings.
|
||||
- Adjust timeout if needed.
|
||||
- Resolve provider-side or network issues.
|
||||
- Correct endpoint/model/profile settings.
|
||||
- Adjust timeout when appropriate.
|
||||
- Resolve provider or network issue.
|
||||
|
||||
Relevant links:
|
||||
Relevant links: [Operations guide](operations.md), [Configuration reference](config.md)
|
||||
|
||||
- [CLI reference](cli.md)
|
||||
- [Configuration reference](config.md)
|
||||
- [Operations guide](operations.md)
|
||||
|
||||
## Prompt Cache Misses Or No Cache Usage
|
||||
## Validation Failed
|
||||
|
||||
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`.
|
||||
- CLI `run` exits `2`.
|
||||
- HTTP returns `200 OK` with `validation.status` set to `failed`.
|
||||
|
||||
Likely cause:
|
||||
|
||||
@@ -309,18 +252,15 @@ Likely cause:
|
||||
|
||||
Diagnostic step:
|
||||
|
||||
- Inspect validation mode and validation errors in CLI summary/HTTP response.
|
||||
- Inspect validation errors in CLI stderr or the HTTP response.
|
||||
|
||||
Safe fix:
|
||||
|
||||
- Refine prompt constraints.
|
||||
- Tighten schema or adjust model/profile settings.
|
||||
- Refine prompt instructions.
|
||||
- Adjust schema or model/profile settings.
|
||||
- Rerun after correction.
|
||||
|
||||
Relevant links:
|
||||
|
||||
- [Configuration reference](config.md)
|
||||
- [Operations guide](operations.md)
|
||||
Relevant links: [Operations guide](operations.md), [HTTP API reference](api.md)
|
||||
|
||||
## Validation Runtime Failure
|
||||
|
||||
@@ -331,55 +271,91 @@ Symptom:
|
||||
|
||||
Likely cause:
|
||||
|
||||
- `json_schema` schema file missing/inaccessible.
|
||||
- Invalid schema JSON document.
|
||||
- `json_schema` schema file is missing or unreadable.
|
||||
- Schema JSON is invalid.
|
||||
|
||||
Diagnostic step:
|
||||
|
||||
- Verify `schema_dir` and `output.schema_path` resolution.
|
||||
- Check schema file readability and valid JSON syntax.
|
||||
- Verify `schema_dir` and prompt `output.schema_path`.
|
||||
- Check schema file readability and JSON syntax.
|
||||
|
||||
Safe fix:
|
||||
|
||||
- Correct schema path.
|
||||
- Fix schema JSON content.
|
||||
- Correct schema path or permissions.
|
||||
- Fix schema JSON.
|
||||
- Rerun.
|
||||
|
||||
Relevant links:
|
||||
Relevant links: [Configuration reference](config.md), [Operations guide](operations.md)
|
||||
|
||||
- [Configuration reference](config.md)
|
||||
- [Operations guide](operations.md)
|
||||
|
||||
## HTTP Request Parsing/Contract Errors
|
||||
## HTTP JSON Or Request Contract Errors
|
||||
|
||||
Symptom:
|
||||
|
||||
- HTTP `400 invalid_json` or `400 invalid_request`.
|
||||
- HTTP `413 request_too_large`.
|
||||
- HTTP `413 response_too_large`.
|
||||
- HTTP returns `400 invalid_json` or `400 invalid_request`.
|
||||
|
||||
Likely cause:
|
||||
|
||||
- Malformed JSON body.
|
||||
- Unknown JSON fields.
|
||||
- Missing required `prompt_id` or `inputs`.
|
||||
- Request body exceeds `server.max_request_bytes`, including inline input bodies.
|
||||
- Encoded JSON response exceeds `server.max_response_bytes`, including generated artifact body and optional raw model output.
|
||||
- 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.
|
||||
- Confirm required request fields are present.
|
||||
- Compare request and expected response sizes to configured HTTP limits.
|
||||
- Revalidate request JSON and compare fields with the API reference.
|
||||
|
||||
Safe fix:
|
||||
|
||||
- Send valid JSON with only supported fields.
|
||||
- Ensure `prompt_id` and at least one input mapping are included.
|
||||
- Use smaller inline inputs, move large local inputs under the artifact root, or increase `server.max_request_bytes`.
|
||||
- Omit `include_raw_output`, reduce generated output size, or increase `server.max_response_bytes`.
|
||||
- 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:
|
||||
Relevant links: [HTTP API reference](api.md)
|
||||
|
||||
- [Operations guide](operations.md)
|
||||
- [CLI reference](cli.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)
|
||||
|
||||
Reference in New Issue
Block a user