Runbook: artifact, request and decision refusals
The refusals Ster states when an artifact, a parsed command line, a desktop request, a workspace import or a decision document cannot be used, each with what it means and what to do. Match the stable source-authored sentence; substituted values are shown as `<PLACEHOLDERS>`. Loading, input, training and numerical refusals are on the [runbook](/docs/runbook).
Artifact I/O and validation#
| Sentence | Meaning | Fix |
|---|---|---|
failed to read steering artifact <PATH> | File cannot be opened. | Correct path/permissions. |
<PATH> is a LoRA adapter sidecar, not a steering artifact: it carries rank and targets where a steering artifact carries trait_name and vectors | A --vector (or /v1 vector) path names an adapter sidecar. The loader recognises the other product's document instead of letting serde escape as a missing field a hundred thousand columns in. | Pass the steering artifact train or optimize wrote. An adapter belongs on --adapter. |
invalid steering artifact JSON in <PATH> | JSON syntax or required field/type is wrong. | Regenerate or repair against schema 1. |
artifact schema <N> is unsupported; this Ster build reads schema 1 | Schema version differs. | Use a schema-1 artifact with this build; do not relabel incompatible data. |
artifact belongs to product "<PRODUCT>", not Ster | Product discriminator is not ster. | Supply a genuine Ster artifact. |
artifact has no steering vectors | Width is 0 or vector list empty. | Retrain/regenerate the artifact. |
layer <L> has vector width <W>, expected <H> | Artifact's own width invariant fails. | Restore untampered output or retrain. |
layer <L> contains a non-finite value | A vector contains NaN/infinity. | Retrain; do not apply it. |
failed to create <PARENT> | Artifact parent directory creation failed. | Fix path/permissions. |
failed to write steering artifact <PATH> | Artifact serialization reached a filesystem write failure. | Fix space, permissions, or destination. |
failed to inspect <PATH> | inspect context wrapper; the next cause is the actual I/O/schema refusal. | Fix the deepest cause. |
<PATH> is a steering artifact, not a LoRA adapter sidecar: it carries trait_name and vectors where an adapter sidecar carries rank and targets | An --adapter (or /v1 adapter) path names a steering artifact. The mirror of the refusal above, written as one: generate takes --vector and --adapter side by side, and an operator who crosses them gets the same sentence from whichever end they crossed. | Pass the adapter weights ster tune wrote. A direction belongs on --vector. |
artifact model "<A>" does not match runtime model "<B>" | evaluate requires exact model-string equality. | Load the artifact's exact model string or retrain. |
artifact was trained for model "<A>", current model is "<B>" | generate model-string gate failed. | Same: exact string match or retrain. |
artifact width <A> does not match model width <M> | Runtime hidden width differs. | Use the training checkpoint/artifact pair. |
layer <L> steering vector width <W> does not match model width <H> | Low-level plan width gate failed. | Supply model-width vectors. |
steering plan contains no vectors | Direct low-level plan construction got no entries. | Supply at least one vector. |
failed to apply steering at layer <L> | Candle rejected broadcast-add during the forward pass. | Treat as model/plan shape or device failure; retain the chained detail. |
Activation export may return failed to write <PATH> for its destination; fix parent permissions/space. Unlike artifact save, export's parent-directory creation may surface a raw OS error without a Ster wrapper.
Both cross-document sentences name the path the reader would recognise: the --vector refusal names the path the operator gave, and the --adapter refusal names the sidecar it derived from the weights — which for a .json path is the same file. Neither is a warning; a document of the wrong kind has no reading that could be right.
CLI parser errors and exit behavior#
Missing required arguments, invalid numeric values, unknown flags/subcommands, an unknown --device (invalid value 'gpu' for '--device <DEVICE>': unknown device "gpu"; expected cpu, metal, or cuda), --precision, --chat-template or train --method, and values outside clap's target type fail before Ster code runs, so a typo never costs a checkpoint load. Clap prints a lowercase error: usage message and exits 2. A known device the binary was not built for, and bf16 on cpu, are refused later, at load, with exit 1. In particular, attach a negative number: --strength=-2.0; --strength -2.0 is parsed as an unexpected flag (the captured build reported error: unexpected argument '-2' found).
After parsing, any anyhow::Result failure exits non-zero and begins with Error:. Progress already written to stderr is not rolled back, and output files are not transactional: if a filesystem fails during a write, inspect or remove the partial destination before retrying.
Desktop request refusals#
ster request <operation> refuses before anything runs with exactly one result event whose status is 2 and whose json is {"error": "<sentence>"}, and exits 2. No log event precedes a refusal (desktop request reference).
| Sentence | When | Fix |
|---|---|---|
unknown operation: <OPERATION> | The argument names no operation. | Use one of the operations ster request --help lists. An HTTP path such as /v1/train is not an operation; the operation is train. |
request body is not valid JSON: <DETAIL> | stdin did not deserialize into the operation's body: malformed JSON, a field of the wrong type, or an unknown field on workspace/import, which denies them. | Write one JSON document to stdin, or nothing for {}. The detail is serde's, with the line and column it stopped at. |
A body that cannot be read at all is not a refusal: Error: failed to read the request body from stdin goes to stderr and the process exits 1 without any event, because nothing on stdout was written yet.
Required request fields
These are pre-run validation sentences, each returned as a status-2 result. Within one operation the fields are checked in the order listed. The tune/* operations list theirs on the desktop request reference.
workspace import requires a source pathvector/train requires a modelvector/train requires a pairs filevector/train requires an output pathvector/optimize requires a modelvector/optimize requires a pairs filevector/optimize requires an output pathvector/evaluate requires a modelvector/evaluate requires a pairs filevector/evaluate requires a steering artifactgenerate requires a modelgenerate requires a promptextract requires a modelextract requires a prompt input fileextract requires an output pathvector/inspect requires a steering artifactpairs inspect requires a pairs filepairs save requires an output pathpairs save requires at least one pairpairs synthesize requires a modelon the local generator,pairs synthesize with the brama generator requires generatorModelon the hosted one, andunknown generator; expected local or bramafor any otherpairs synthesize requires a trait descriptionpairs synthesize requires an output pathpairs synthesize requires a pair count above zerodecide requires a modeldecide requires a request with a state and questions, then any request refusal from the decision refusals belowcalibrate requires a modelcalibrate requires an examples pathcalibrate requires an output path
A failure after the operation starts is not a refusal: its sentence arrives as the last log event, prefixed error: , the result has status: 1 and json.error, and the process exits 1. Gate success on the result's status or on the exit status. A successful request ends with exactly one status: 0 result and exits 0. A process that ends with no result event at all was killed or crashed, and its stderr says why; Ster Desktop reports that case as The run ended with status <N> before a result was received. followed by the stderr text.
Workspace import refusals#
status: rejected— source JSON is unreadable, has unknown fields, contains no pairs, contains an empty side, or--nameviolates the identifier rule. No pair file or manifest entry is committed.status: conflicting— the logical name or destination already belongs to different content. Choose another--name; Ster preserves the existing set.active Ster pair set is missing— an indexed file was removed outside Ster. Import it again. The manifest is not silently healed to another set.
Decision refusals#
ster decide and ster calibrate check their documents before a weight is mapped, so every sentence below costs milliseconds and exits 1. Under ster request decide, the request's own refusals — the a decide request …, question, option and level rows — are checked before anything runs and return a status-2 result. The rest read a file or the tokenizer, so under ster request they arrive after the operation has started, as the last error: log event and a status-1 result. The command pages (decide, calibrate) say what each field is.
| Sentence | What to do |
|---|---|
a decide request has an empty state | Put the content to judge in state; a string or any JSON value. |
a decide request needs at least one question | Add a question under questions. |
a decide request has a question with an empty id | Give every question a non-blank id. |
question '<id>' has empty instructions | Write the question in instructions. |
choice question '<id>' needs at least two options | A choice with one option is not a choice; add options or ask a noul. |
choice question '<id>' has <n> options; Ster labels at most 26 | Every option is answered by one letter. Split the question or shortlist first. |
choice question '<id>' has an option with an empty name "<name>" | Name every option; the name is what the answer returns. |
score question '<id>' needs at least two levels | A scale needs two levels at least. |
score question '<id>' has <n> levels; Ster labels at most 26 | Fewer, better-described levels. |
score question '<id>' has an empty description at level <i> | Describe the level; the model reads only the descriptions. |
invalid decide request <path> / invalid decide request on standard input | The reader's cause is beneath it: a missing field, a wrong type, or malformed JSON. |
question '<id>' renders to <n> tokens, past the <max> this model was built for | Shorten the state or the options, or use a model with a longer context. |
this tokenizer has no single token for the answer label "<label>", so it cannot be read from one position | This checkpoint's vocabulary cannot spell that letter as one token; fewer options, or another checkpoint. |
calibration needs at least one labelled example | The examples array is empty. |
calibration needs at least one labelled question | No example carries an answers entry. |
calibration example <i> is not a valid request | The request refusal beneath it names the field. |
example <i> labels question '<id>', which it does not ask | The answers key must be one of that example's question ids. |
example <i> answers question '<id>' with <label>, which is not one of its options | A choice is labelled with an option name, a score with a level index, a noul with true or false. |
invalid calibration <path> / invalid calibration examples <path> | The document is not the schema the page describes; the cause is beneath. |
calibration <path> has schema "<schema>"; this Ster reads ster-calibration/1 | Refit with this Ster. |
calibration <path> has a temperature that is not a positive number | The artifact was edited by hand; refit. |
calibration <path> was fitted for model '<fitted>', not '<loaded>' | A temperature belongs to one checkpoint. Refit on the model you are deciding with. |