Troubleshooting

The engine logs one JSON object per line on stdout. A startup failure is a single startup_failed line whose message is one of those below. Request errors come back in the route’s JSON envelope with the status shown.

Startup

Message	Cause and fix
`a license key is required: pass --license-key <LSK-...> or set LAYERSCALE_LICENSE_KEY`	No key. Get one at layerscale.ai/get-license.
`license key must start with LSK-`	The value is not a LayerScale key. Check for a truncated or wrong variable.
`license key contains invalid characters`, `license key decodes to N bytes, expected 112`	The key was mangled when copied.
`license key signature is invalid`	The key was not issued for this engine, or has been edited.
`license expired at unix ...`	Past the key’s expiry and its two-day grace. Renew at layerscale.ai/pricing.
`license permits at most N GPU(s) (M requested; pass --tp N)`	The host shows more GPUs than the license allows and no `--tp` was given. Pass `--tp N`.
`--model <DIR> is required; run --help for usage`	Every command needs `--model`.
`unknown command '...'; run --help for usage`	A flag was mistyped and landed as the command, or the command was misspelled.
`config.json: architecture '...' is not implemented`	The model family is not supported. The message lists the families this build knows.
`layer N needs ..., which the GPU backend does not implement`	The checkpoint uses a layer feature (a non-causal mask, a sigmoid router, a rotary variant, attention temperature scaling) outside the supported set.
`no tokenizer.json or tekken.json in ...`	The directory has no tokenizer. Check the download completed.
`model.safetensors.index.json: missing 'weight_map'`	The shard index is damaged; download the checkpoint again.
`config.json has no max_position_embeddings; pass --ctx`	The checkpoint does not state a context length.
`the KV pool is N tokens but --ctx is M; one full context must fit`	Not enough memory for one context after the weights. Raise `--gpu-memory-utilization` or `--max-total-tokens`, lower `--ctx`, use `--kv-cache-dtype fp8`, or add GPUs with `--tp`.
`--gpu-memory-utilization X is not in (0, 1]`	The value must be a fraction above 0 and at most 1.
`this checkpoint's tokenizer has no ... token, so it was not trained on the ... chat template this engine renders for its architecture`	The checkpoint uses a template variant the engine does not render for this architecture.
`--kv-cache-dtype fp8 needs head_dim 128 and this model's is ...`	fp8 KV needs `head_dim` 128. Use `bfloat16`.
`quant_method '...' is not implemented`	An unsupported quantization format; see Models.
`--device cuda: this build is CPU`	The binary was built without a GPU backend; the published images carry one.
`cannot bind ADDR: ...`	The port is taken or the address is not local.

GPU and container

Symptom	Cause and fix
`no kernel image is available for execution on the device`	The GPU is older than Hopper. The image supports Hopper and Blackwell only.
The container exits at once with a CUDA driver error	The host driver is too old for CUDA 13.3, or the container was started without `--gpus`.
The port refuses connections after start	Expected: the engine binds after loading and warming up. Follow the logs for `ready`.
`/health` answers 503	The engine thread stopped or stalled. Restart the container and check the last `error` line in the log.

Requests

Status and message	Meaning
401 `missing or invalid license key; send it as 'Authorization: Bearer <LSK-...>'`	Send the key the server was started with, as a bearer token or `x-api-key`.
400 `prompt has N tokens but the context limit is M (raise --ctx)`	The conversation no longer fits. Trim it, or restart with a larger `--ctx` (a free license caps it at 32,768).
400 `'...' is not supported`	A request parameter the engine refuses by name. The API reference lists what each route accepts.
400 `'max_tokens' is required`	`/v1/messages` requires it, as Anthropic’s API does.
400 `'stop' takes at most 4 sequences`	Send at most 4 stop strings of at most 64 bytes each.
404 `no such session '...'`	Sessions must be created with `POST /v1/sessions` first.
409 `session '...' has a request in flight`	One request per session at a time. Wait for it, or delete the session.
409 `session '...' already exists`	Pick another id, or delete the old session.
403 `the free license permits at most 1 live session(s); delete one first`	The free tier’s session limit. Delete a session or upgrade to Pro.
408 `request took too long to arrive`	The full request did not arrive within 60 seconds.
413 `body too large`	Bodies are limited to 32 MiB.
503 `server is holding too many request bodies`	More than 256 MiB of request bodies are buffered at once. Retry.
500 `engine stopped`	The engine thread has died. `/health` answers 503 too; restart.

A streaming response that fails after it has started carries the error as its last data: frame (or an error event on /v1/messages), because the status line is already 200.

Output quality

Sampling defaults are temperature 0.6 and top_p 0.9. Send "temperature": 0 for greedy output.
Prompt-lookup speculative decoding is on by default and is not bit-exact against a plain decode. Start with --speculative-algorithm none when comparing outputs across runs or engines.
A tool call the model wrote but the engine could not parse is returned as plain content. The tool_call_unparseable log line and the layerscale_tool_calls_malformed_total metric show when this happens.
A reply cut off at max_tokens has finish_reason: "length"; raise it.

Performance figures for supported models and GPUs are at layerscale.ai/benchmarks.