Troubleshooting

Most failures announce themselves with a status code or a line in the server’s log. This page collects the ones the documentation explains.

Figure · Symptoms

What you see, why, and what to do: ten things the documentation says.

• Connection refused right after the startThe server is still starting: the first start downloads the checkpoint and warms the engine.Wait until GET /health answers.
• 422 on a requestThe request is malformed, or the prompt is longer than the 32,768-token context; the detail names what is wrong.Read the detail; shorten the state or the question and send it again. The server stays up.
• 400 on a requestThe engine cannot answer it, for example a choice with more than 255 options.Cut the options to 255 or fewer.
• 503 on every request, and /health answers 503The engine died; the server is about to exit with code 70.Let your restart policy bring a new server up; read the reason in the body.
• The server will not start and mentions VLLM_USE_DEEP_GEMMThe server refuses to start when it is set to anything other than 0.Unset it, or pass --allow-deep-gemm if you mean it.
• The server refuses a model repositoryThe repository's decision_config.json differs from the installed profile; the message names the keys and the release it was made for.Use the repository revision made for your release, or install that release.
• WARNING: tasks fitted under another model or rendering are not applied at the startThe tasks were fitted under another model, prompt or yes/no rendering.Register them again from their examples, or start with --prompt-tail compact --noul-rendering words if they were fitted under the earlier layout.
• No x-decisio-tasks header on a question you registeredThe question matched no task: its type, options or order differ from the registration.Ask it exactly as registered; renaming, adding or reordering an option makes a different task.
• Answers that differ between runsRepeatability is stated per base: the Qwen base repeats, the Gemma bases can move slightly and near-tied choices can change between sessions.Read the determinism notes before treating a difference as a fault.
• The first request after a start is slowIt warms the engine; a long state seen for the first time also takes longer on the larger bases.Send a few requests first, and raise a client's timeout for long states.

Each row is a statement of decisio's own documentation; the sections below say more.

Source: docs/api.md, docs/running.md, docs/tasks.md, docs/cli.md and docs/migrating.md at the pinned release.

TL;DR

Start with what the server says about itself:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/health
curl -s http://127.0.0.1:8000/v1/tasks
# 200 when the engine is up, 503 when it has died, and 000 while nothing answers yet (the server is still starting)
# the registered tasks, whether tasks are applied, and the server's fingerprint

Run against the CPU stand-in at v0.11.1 on 2026-10-14.

Word	Meaning
422	the request is malformed or the prompt is too long; the detail says what
400	the engine cannot answer the request
503	the engine has died
fingerprint	the model and rendering a task is fitted under; a task is applied only by a server with the same one

1. Is it up?

A connection refused right after a start means the server is still starting: the first start downloads the checkpoint and warms the engine. /health answers once it is ready (7 min 54 s for the 31B’s first start, with its download, on the measured machine). A 503 means the engine died; the server exits with code 70 and a restart policy brings a new one (Health and monitoring).

2. Is it the request?

A 422 or a 400 comes with a detail that names what is wrong; read it first. A prompt over 32,768 tokens is a 422 that says the rendered prompt is longer than the context, and a choice with more than 255 options is a 400. The model field does not choose a model, and fields the server does not know are ignored, not rejected.

3. Is it the tasks?

No x-decisio-tasks header on a question you registered means it matched no task: ask it exactly as registered. A server that prints WARNING: tasks fitted under another model or rendering are not applied at start was given tasks fitted under something else; register them again from their examples (Teach it your question).

4. Is it the answer?

Answers can differ between runs on the Gemma bases, which do not repeat bit for bit, and between sessions on the 31B for near-tied options. That is stated per base in the evaluation card; it is not a fault.

What next

• Health and monitoring: what /health and the headers report.
• Flags and options: every flag, including the ones a start can refuse on.
• The HTTP API: every status and field.