Ster/Docs

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#

SentenceMeaningFix
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 vectorsA --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 1Schema version differs.Use a schema-1 artifact with this build; do not relabel incompatible data.
artifact belongs to product "<PRODUCT>", not SterProduct discriminator is not ster.Supply a genuine Ster artifact.
artifact has no steering vectorsWidth 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 valueA 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 targetsAn --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 vectorsDirect 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).

SentenceWhenFix
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 path
  • vector/train requires a model
  • vector/train requires a pairs file
  • vector/train requires an output path
  • vector/optimize requires a model
  • vector/optimize requires a pairs file
  • vector/optimize requires an output path
  • vector/evaluate requires a model
  • vector/evaluate requires a pairs file
  • vector/evaluate requires a steering artifact
  • generate requires a model
  • generate requires a prompt
  • extract requires a model
  • extract requires a prompt input file
  • extract requires an output path
  • vector/inspect requires a steering artifact
  • pairs inspect requires a pairs file
  • pairs save requires an output path
  • pairs save requires at least one pair
  • pairs synthesize requires a model on the local generator, pairs synthesize with the brama generator requires generatorModel on the hosted one, and unknown generator; expected local or brama for any other
  • pairs synthesize requires a trait description
  • pairs synthesize requires an output path
  • pairs synthesize requires a pair count above zero
  • decide requires a model
  • decide requires a request with a state and questions, then any request refusal from the decision refusals below
  • calibrate requires a model
  • calibrate requires an examples path
  • calibrate 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 --name violates 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.

SentenceWhat to do
a decide request has an empty statePut the content to judge in state; a string or any JSON value.
a decide request needs at least one questionAdd a question under questions.
a decide request has a question with an empty idGive every question a non-blank id.
question '<id>' has empty instructionsWrite the question in instructions.
choice question '<id>' needs at least two optionsA choice with one option is not a choice; add options or ask a noul.
choice question '<id>' has <n> options; Ster labels at most 26Every 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 levelsA scale needs two levels at least.
score question '<id>' has <n> levels; Ster labels at most 26Fewer, 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 inputThe 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 forShorten 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 positionThis checkpoint's vocabulary cannot spell that letter as one token; fewer options, or another checkpoint.
calibration needs at least one labelled exampleThe examples array is empty.
calibration needs at least one labelled questionNo example carries an answers entry.
calibration example <i> is not a valid requestThe request refusal beneath it names the field.
example <i> labels question '<id>', which it does not askThe answers key must be one of that example's question ids.
example <i> answers question '<id>' with <label>, which is not one of its optionsA 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/1Refit with this Ster.
calibration <path> has a temperature that is not a positive numberThe 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.