A Model or Binding Isn't Running

A model that won't run almost always fails because of something feeding it, not the model itself. The fastest path to the root cause is to work down the chain: model, then bindings, then the tags each binding reads, then the devices those tags live on. This page follows that order.

Koios records three diagnostic fields (error code, error message, error detail) at both the model level and the binding level. For how those fields behave, how errors auto-clear, and the full status and quality legend, see Reading Status, Quality & Errors. This page focuses on what the model and binding error codes mean and how to act on them.

Start with the Bindings Tab

When a model fails, the model-level error is often generic — it tells you the model couldn't run but not which input caused it. The binding-level errors tell you the actual cause: a disabled tag, a missing range, stale history, an on-demand read timeout.

Where each error appears:

Model detail, Overview tab — the status hero shows the current state. A red strip below the status carries the model error message and detail whenever the model has one. The strip follows the error, not the status, so it also appears on a model that is not Failed — such as one held back by an invalid configuration.
Model list — each model shows a colored status icon. Hover it to read the error message. The icon is not always red: an enabled model held back by an invalid configuration shows the grey spinner instead, and the tooltip still carries the message.
Bindings tab — every input and output binding is a card with a colored left border. A failed binding turns red and expands to show its error message and detail inline. This is the diagnostic view that points at the specific binding that broke the model.

Bindings first, always

The model-level error tells you a binding failed. The binding-level error tells you which one and why. Open the Bindings tab before anything else. The one exception is a model reporting Model configuration is invalid — there the bindings are written Stopped with no error of their own, and the reason lives only on the model. See Model Configuration Errors.

How the Inference Pipeline Runs

Reading the pipeline order helps you read error codes: the code tells you which stage failed. Each inference cycle runs these steps, stopping at the first failure:

Validate bindings — each input tag is assigned, enabled, and running
Query history — fetch historical data from the time-series database
Preprocess — interpolate, check ranges, normalize, assemble the input tensor
Run inference — execute the ONNX or TFLite model
Write results — de-normalize predictions, check output ranges, write to output tags

For the exact tensor shapes, input depth, and normalization rules the preprocess and inference steps depend on, see Model Inference Requirements.

Model Error Codes

These apply to the model as a whole. When you see one, check the bindings for the more specific cause. An error code of 0 (None) means no active error.

File errors

Code	Meaning	What to do
2	No File Found — no file has been uploaded, or a file is present but would not load	The error message tells you which: No model file loaded means upload an ONNX or TFLite file on the Files tab; Model file failed to load carries the underlying reason in the error detail. Re-upload the file.

A bad file is rejected at upload, not at run time

Koios validates every model file when you upload it — a corrupt file, a non-ONNX/TFLite file, an ONNX exported above IR version 13, or one using operators the runtime does not implement is refused with an explanatory message right there in the upload dialog. Re-export at IR 13 or lower (or annotate it with the koios-model-utils library, which clamps the IR version) and upload again. Because of that gate, a bad file cannot reach a running model.

Configuration errors

Code	Meaning	What to do
6	Bindings Invalid State — the model's configuration failed the load-time check	See Model configuration is invalid below, then Model Configuration Errors for the reason-by-reason fixes.

Inference errors

Code	Meaning	What to do
9	Binding Prediction Index Missing — an output binding's Output Index doesn't match any output position	Reconcile output indices against the model architecture.
11	Failed to Write Predictions — results could not be written to the live data cache	Rare; usually a cache connectivity issue.

System errors

Code	Meaning	What to do
13	Generic Exception — an unclassified error; the detail carries the exception	Check the model logs for the full stack trace. This is where inference-time failures land — an input tensor the model would not accept, a shape mismatch, or a scaling failure.
999	Unlicensed — the license does not cover this model	See Licensing Problems.

Model configuration is invalid (code 6)

Koios checks a model's configuration every time it loads it, and refuses to run one that would assemble the wrong input. When that check fails, the model reports:

Error code 6 — Bindings Invalid State
Error message Model configuration is invalid
Error detail — the exact reason, naming the binding or number at fault

An enabled model spins at Starting and never runs

The stored status is Stopped, not Failed. Because the model is still enabled, the interface reads that as Starting with a grey spinning icon, and it stays there indefinitely — a model that spins and never reaches Running is the symptom to recognize. The red error strip appears under the status all the same, carrying the message and the reason. Its bindings are written Stopped with no error of their own, and the scheduler skips the model entirely, so pressing Start does nothing until the configuration is corrected. There is nothing to acknowledge: once the configuration validates, the error clears on the next reload and the model resumes.

Read the model's Error Detail first — it names the input, order, or number at fault, and on this one failure it is the only place the reason exists. Every reason, what it means, and how to correct it is on Model Configuration Errors.

Duplicate binding orders stop models that used to run

Duplicate input binding orders were previously tolerated and silently merged two inputs into one column. They are now rejected, so a model configured that way stops after upgrading. Binding order is not editable on the Bindings tab — Koios assigns it from the model file. To renumber, export the model's bindings to CSV, give each input a distinct order, and import the file back. See Duplicate Input Binding Order.

Structured input models

A model can declare a structured input space, where each input binding carries its own window length, sample rate, and interpolation setting rather than sharing one model-wide window. Warm-up, retention, and the depth and staleness checks are then sized per input: one binding can be ready while another is still filling, and the model waits for all of them.

Three behaviors to know:

Memory Only must be off. A structured model with Memory Only enabled stops with Model configuration is invalid and the detail Structured input spaces do not support in-memory history yet — disable Memory Only for this model. Per-input in-memory buffers are not available in this release.
Only PCHIP interpolation is applied. If a binding requests any other interpolation method, Koios falls back to PCHIP and writes a warning to the model's log when the model loads. The selection is preserved but has no effect yet — check the model log if resampled values are not what you expect.
Binding orders must be unique and dense. Inputs are keyed by their binding order when the tensor is assembled, so every input needs a distinct order running 1..N. Koios assigns these from the model file; correcting a stored duplicate or gap is a binding CSV export and import. See Model Configuration Errors.

Binding Error Codes

These apply to individual input or output bindings and are the most actionable diagnostics. A binding can fail at any pipeline stage; the groups below follow the chain from tag state outward. Code 0 (None) means the binding is healthy.

Tag-state errors — fix at the tag or device, not the model

Code	Meaning	What to do
11	Binding Tag Disabled — the bound tag is stopped	Enable the tag or its parent device.
13	Binding Tag Failed — the bound tag is in a failed state, including a failed or bad-quality read	Fix the tag's own error. See Bad, Missing, or Frozen Tag Values.
14	Binding Tag Not Assigned — no tag selected for this binding	Assign a tag on the Bindings tab.
17	Upstream Model Failure — this input is written by another model whose output is currently failing	Fix the upstream model first. This binding recovers automatically.

On-demand read timeout

Code	Meaning	What to do
20	On-Demand Read Failed — the device did not respond to the on-demand read within the timeout	Confirm the device is online and reachable, then raise the On-Demand Timeout on the model or scan group. The read timeout is frequently caused by batch-window latency (see below).

Batch window adds latency before the device is even read

On a device configured for on-demand scanning, the batch window can delay a read by up to its full duration before the device is polled. The model's on-demand timeout must cover batch window + device read time, or you'll see On-Demand Read Failed even on a healthy device. See On-Demand Scanning for the batch-window mechanics and On-Demand Inference for the model-side timeout.

Historical-depth and staleness errors — the tag works, the history doesn't

Code	Meaning	What to do
1	Not Enough Historical Depth — not enough samples to fill the model's input window	Common right after a model is enabled. Wait for enough scan cycles to accumulate the required depth; the detail shows how much more is needed.
2	Stale History Data — the most recent point is too old to use	The tag's device has stopped collecting or data is arriving late. The detail shows how far outside the allowed window the data is.

New models need to warm up

When you first enable a model, its input bindings show Not Enough Historical Depth until the device has collected enough scan cycles to fill the sample window. This is normal — the model starts running on its own once enough data accumulates. For flat and time-series models the window is model-wide (depth × sample rate) and comes from the model file. For a structured input model each input has its own window and rate, so warm-up completes per input rather than all at once. See Model Inference Requirements.

If a binding shows Stale History Data but the tag itself looks live, the gap is in historization, not collection. See Data Is Stale, Frozen, or Has Gaps.

Range, normalization, and calibration errors

Code	Meaning	What to do
3	No Range Given — a normalization range is required but not configured	Set Range Min and Range Max on the tag, or set Parameter Source to Custom on the binding and fill in Custom Minimum and Custom Maximum. For Z-Score, set Custom Mean and Custom Std Dev.
4	Invalid Range Given — the range is invalid (min ≥ max, or Z-Score std dev is zero)	Correct the range values on the tag or binding.
5	Value Out of Range — an input or output value exceeded the configured failure bounds	The detail shows the value and the bound it crossed. Review the failure range, or widen it if the value is expected.
21	Invalid Calibration — the calibration gain is zero or produced an invalid value	A zero gain divides by zero on write-back. Set a non-zero gain on the Bindings tab.

Rate-of-change error

Code	Meaning	What to do
19	Rate of Change Exceeded — the value changed faster than the configured threshold	A safety check. The detail shows the actual rate, threshold, and direction. If the rate is expected, raise the ROC threshold under Failure in the binding drawer.

Data-structuring errors

Code	Meaning	What to do
16	Failed to Structure Input Data — the preprocessed data could not be assembled into a valid input tensor	Usually a mismatch between the data shape and what the model expects. See Model Inference Requirements.

Output and write errors — after inference

Code	Meaning	What to do
8	Prediction Index Missing — the model output has no value at this binding's Output Index	Verify the output index matches the model architecture.
9	Failed to Scale Prediction — the predicted value could not be de-normalized to the tag's scale	Check the output binding's normalization range.
18	General Model Failure — the model produced no prediction, so this output has no value	The root cause is in the input bindings or the model-level error. Check those first.

Other

Code	Meaning	What to do
999	Unlicensed — the license does not cover this binding	See Licensing Problems.

Common Scenarios

All inputs show "Tag Disabled"

Every input binding is code 11. The model depends on tags that have been stopped, individually or because their parent device was disabled. Re-enable the tags or the device.

All inputs show "Not Enough Historical Depth"

Normal right after enabling a model or restarting a device. Wait for the device to complete enough scan cycles to fill the window — model-wide (depth × sample rate) for flat and time-series models, or per input for a structured input model. No action needed.

One input shows "Upstream Model Failure"

That binding reads a tag written by another model's output, and the upstream model is failing. Fix the upstream model; this binding recovers on its own.

Running, but an output shows "Value Out of Range"

Inference produced a prediction that exceeded the output's failure bounds. Likely causes:

Input data has drifted outside the range the model was trained on
Failure bounds are set too tightly for the expected output
The normalization range doesn't match the training data's range

Review the output binding's failure range under Failure in the binding drawer.

"On-Demand Read Failed"

The model or its scan group is on-demand, but the device didn't answer in time. Confirm the device is powered and reachable (see Troubleshoot a Connection), then confirm the On-Demand Timeout covers the batch window plus device read time. See On-Demand Scanning.

"Input tensor shape mismatch"

The number of input bindings doesn't match what the model file expects, usually after a file with a different architecture was put in place. You don't add or remove bindings by hand — re-activate the model's intended file on the Files tab and activation rebuilds the binding set to match, keeping the tag assignments on the bindings it retains. See Managing Model Files and Model Inference Requirements.

A scan group fails and every model in it shows "On-Demand Read Failed"

When a scan group's shared on-demand read fails, all models in the group fail together. The group-level error (On-Demand Read Failed, scan-group code 2) appears on the scan group's detail page. Fix the shared device connection; every model in the group recovers on the next cycle. For scan-group health more broadly, see Service Health & Resource Alarms.

If a Model Stays Stuck

Errors clear automatically once the next inference cycle succeeds — no manual acknowledgment. If a model won't recover:

Read the Bindings tab for per-binding errors; they are more actionable than the model-level error.
Set the model's log level to Debug on the Logs tab and watch each pipeline stage.
Confirm every input tag is enabled and running — one disabled or failed tag blocks the whole model.
Check the tag devices — a down device fails all its tags, which cascades to every model using them.
Toggle the model off and on with the Enabled switch.

If none of that clears it, gather logs before opening a ticket. See Collecting Diagnostics for Support.

What's Next

Model Configuration Errors — the load-time check behind error code 6, every reason it reports, and how each one is corrected
Reading Status, Quality & Errors — the shared error-field reference, status/quality legend, and stuck-error checklist
Model Inference Requirements — input/output tensor shapes, input depth, normalization
On-Demand Inference — model-side on-demand cycle and timeout
On-Demand Scanning — device-side freshness and batch-window latency
Bad, Missing, or Frozen Tag Values — when a binding's tag is the problem
Data Is Stale, Frozen, or Has Gaps — when history is stale but the tag is live
Troubleshoot a Connection — when the device feeding a tag is unreachable
Service Health & Resource Alarms — scan-group and predict-engine health
Licensing Problems — the Unlicensed (999) code
Collecting Diagnostics for Support — what to gather before a ticket

Expression & Value-Mapping Errors Data Is Stale, Frozen, or Has Gaps