Model Configuration Errors

Koios checks a model's configuration every time it loads one, and refuses to run a model whose bindings would assemble the wrong input vector. Rather than inferring on a tensor that is silently wrong — a dropped signal, two inputs collapsed into one column, a window that does not match the one the model was trained on — the model is stopped before its first scan and the reason is recorded on the model.

This is a deliberate fail-closed design: a model producing quietly wrong predictions is worse than a model that does not run.

Fail-Closed, Not Failed

A configuration failure is not an inference failure, and it does not behave like one.

Behavior	What happens
Status	The stored status is Stopped, not Failed. Its error code is 6 (Bindings Invalid State) and its error message is Model configuration is invalid
Error detail	The specific reason, naming the binding, order, or number at fault
Bindings	Every input and output binding is written Stopped with no error of its own — the reason lives only at the model level
Scheduling	The model is never queued. A model in a scan group is skipped as a member; the group and its other models keep running normally
Start	Enabling the model records it as enabled but does not start it. It never scans, and the error stays on screen
Recovery	Nothing to acknowledge. The next load that validates clears the error and the model resumes

An enabled model that cannot scan reads as Starting

Stopped is the stored status, but it is not what you read on screen for an enabled model. Koios shows an enabled model that is Stopped as Starting, with a grey spinning icon, because that is normally a model a second away from its first prediction. A model held back by an invalid configuration sits in that state indefinitely, so a model that spins at Starting and never reaches Running is the signature symptom — read the error strip under the status rather than waiting it out. Turn the model off and it reads plain Stopped; the error and the strip stay either way.

Where the Reason Appears

Location	What you see
Overview tab	A red strip below the status hero carrying Model configuration is invalid followed by the detail. The strip follows the error, not the status, so it appears even though the model is not Failed. Click it to copy the full text
Parameters tab	Error Code, Error Message, and Error Detail in the Live Data section
Logs tab	The model log records the rejection at Error level when the configuration loads, and the recovery at Info level
Model list	A grey spinning icon (Starting) while the model is enabled, a grey Stopped icon once it is disabled. Hover it for the message
Bindings tab	Every card Stopped, no per-binding error

ERROR  Configuration invalid, model will not scan: Input binding_order values
       must be unique; got [1, 1, 3]
INFO   Configuration is valid again, clearing config error

This is the one case where bindings-first does not apply

For every other model failure, the binding-level error is the actionable one and the model-level error is generic — see A Model or Binding Isn't Running. A configuration failure inverts that: the bindings are written Stopped with a clean slate, and the model's Error Detail is the only place the reason exists.

When the Check Runs

The check runs on every path that loads or reloads a model, which is also every path that could fix one.

Event	Re-runs the check
Predict Engine starts	Yes
Saving the model's Configuration tab	Yes
Saving a binding	Yes
Activating a model file	Yes
Editing a bound tag's configuration	Yes
Turning the model off and on	No

Toggling the model does not re-check it

Enabling and disabling a model sends a start or stop instruction, not a configuration reload, so the stored error stands. Correcting the cause is what clears it — and because correcting it means saving a binding, saving the model, or activating a file, the clear happens on its own, without a service restart.

Duplicate Input Binding Order

The most common reason, and the only one that applies to every model rather than just structured input models.

The detail reads Input binding_order values must be unique, followed by the orders it found — for example [1, 1, 3].

Input columns are keyed by binding order when the input vector is assembled, so two inputs sharing an order collapse into one column: one signal is written twice and the other never reaches the model. Duplicates were previously tolerated and silently merged, which is why this most often shows up as a model that ran for months and stopped immediately after an update.

Binding order is assigned by Koios from the model file's input count, not chosen by hand, and Koios now rejects a save or an import that would give two inputs of the same model the same order. A duplicate you find today is stored configuration that predates that rule.

To renumber:

Export the model's bindings from the model list. See Importing & Exporting Models.
In the exported CSV, give each input row a distinct binding_order in a dense 1..N run, leaving the id column untouched.
Import the corrected file.

Renumber into free slots, not by swapping

Each row is validated as it is saved, so a straight swap of two orders fails: the first row saved collides with the order the second row still holds. Move duplicates into orders nothing currently uses, then close the gaps in a second import.

Binding Count Doesn't Match the File

For a model with no structured input space, the detail reads Model expects N input feature(s) but M input binding(s) are configured.

Koios reconciles the binding set against the file's input count when you activate a file, so this appears when the binding set has drifted from the width the graph actually accepts — usually after a file with a different architecture was put in place. Re-activate the model's intended file on the Files tab; activation adds or removes input bindings to match, preserving the tag assignments on the bindings it keeps. See Managing Model Files.

Structured Input Space Mismatches

A model whose active file declares a structured input space is checked much more strictly, because each input carries its own window length and sample rate and those windows have to tile the flat vector exactly.

Error detail says	What it means	Fix
Structured input spaces do not support in-memory history yet	Memory Only is on. Per-input in-memory buffers are not available in this release, and nothing blocks saving the combination	Turn Memory Only off on the Configuration tab
Input `binding_order` must be dense 1..N	The orders have a gap. Every input from 1 to N must exist exactly once	Renumber as described above
Binding/leaf count mismatch	The model has a different number of input bindings than the space has inputs	Re-activate the file so the binding set is rebuilt from it
Input N window length is x but the observation space declares y	That input's window disagrees with the file. The per-input windows are declared by the file, not derived from the graph	Re-activate the file, or re-export the model with the window you want
Per-leaf window lengths sum to x but the observation-space flatdim is y	The same mismatch seen in aggregate: the windows do not tile the flat vector	As above
Observation flatdim x does not match the graph input feature dim y	The space describes a wider or narrower vector than the graph accepts	Re-export the policy so the flattened space matches the graph
Input binding(s) N have a non-positive leaf sample rate or window length	An input resolves to zero samples or a zero cadence	Set a positive Sample Rate on that binding's Sampling section
Structured models require a rank-2 (flat) graph input	The file's graph is a time-series shape, which cannot be carved into per-input windows	Re-export the policy with a flattened observation space
Unsupported observation-space `schema_version`	The file was written by a newer library than this release reads	Re-export with a supported version of `koios-model-utils`

Interpolation fallback is a warning, not a configuration error

An input that requests any method other than PCHIP does not stop the model. This release resamples every input with PCHIP and records a warning in the model log when the configuration loads. The selection is stored and takes effect in a later release.

Clearing the Error

Read the Error Detail on the Overview strip or the Parameters tab. It names the input, order, or number at fault.
Make the correcting change — a binding, the Configuration tab, or activating a file.
Watch the model's status. Saving is itself the reload, so the error clears within a second or two and the model returns to Stopped with no error.
If the model is enabled and standalone, it is queued again immediately. A model in a scan group rejoins on the group's next scan.
The first cycle after that decides Running or Failed on its own merits — a model that clears its configuration error can still fail on a disabled tag or a short history window. See A Model or Binding Isn't Running.

If the detail is unchanged after your edit, confirm the change was actually saved: a binding drawer discards its edits on Cancel or on closing without saving.

What's Next

A Model or Binding Isn't Running: every other model and binding error code, worked down from the model to the devices
Reading Status, Quality & Errors: the status legend behind Stopped, Starting, and Failed, and where each error field surfaces
Structured Input Spaces: per-input windows, sample rates, and the restrictions that produce most of these errors
Assigning Bindings: the binding settings behind each input and output
Managing Model Files: uploading, activating, and how activation reconciles bindings
Importing & Exporting Models: the binding CSV columns, including binding_order

Troubleshooting a Model Components