---
title: "Model Configuration Errors"
description: "Why a model whose configuration would assemble the wrong input is left Stopped instead of Failed, what each reason means, and how the error clears"
source_url: https://ai-ops.com/docs/models/troubleshoot-configuration-errors
---

# 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](https://ai-ops.com/docs/models/scan-groups.md) 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 |

> [!WARNING] 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 |

```text
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
```

> [!TIP] 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](https://ai-ops.com/docs/troubleshoot/models.md). 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** |

> [!NOTE] 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](https://ai-ops.com/docs/models/structured-input-spaces.md).

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:

1. Export the model's bindings from the model list. See [Importing & Exporting Models](https://ai-ops.com/docs/models/importing-exporting.md).
2. In the exported CSV, give each input row a distinct `binding_order` in a dense `1..N` run, leaving the `id` column untouched.
3. Import the corrected file.

> [!WARNING] 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](https://ai-ops.com/docs/models/model-files.md).

---

## Structured Input Space Mismatches

A model whose active file declares a [structured input space](https://ai-ops.com/docs/models/structured-input-spaces.md) 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](https://ai-ops.com/docs/models/configuring-a-model.md#memory-only) |
| 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` |

> [!NOTE] 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

1. Read the **Error Detail** on the Overview strip or the Parameters tab. It names the input, order, or number at fault.
2. Make the correcting change — a binding, the Configuration tab, or activating a file.
3. 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.
4. 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.
5. 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](https://ai-ops.com/docs/troubleshoot/models.md).

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](https://ai-ops.com/docs/troubleshoot/models.md): every other model and binding error code, worked down from the model to the devices
- [Reading Status, Quality & Errors](https://ai-ops.com/docs/troubleshoot/reading-status-and-errors.md): the status legend behind Stopped, Starting, and Failed, and where each error field surfaces
- [Structured Input Spaces](https://ai-ops.com/docs/models/structured-input-spaces.md): per-input windows, sample rates, and the restrictions that produce most of these errors
- [Assigning Bindings](https://ai-ops.com/docs/models/assigning-bindings.md): the binding settings behind each input and output
- [Managing Model Files](https://ai-ops.com/docs/models/model-files.md): uploading, activating, and how activation reconciles bindings
- [Importing & Exporting Models](https://ai-ops.com/docs/models/importing-exporting.md): the binding CSV columns, including `binding_order`