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. When the model is Failed, a red strip below the status shows the model error message and detail.
Model list — each model shows a colored status icon. Hover the red icon to read the error 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.

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
1	No File Given — no model file uploaded	Upload an ONNX or TFLite file on the Files tab.
2	No File Found — the referenced file is missing from storage	Re-upload the file on the Files tab.
3	Failed to Parse File — corrupt, not a valid ONNX/TFLite, or an ONNX IR version above 13	Verify the file opens in your training environment; if it was exported at a newer IR version, re-export at IR 13 or lower (or annotate it with the model-utils library, which clamps the IR version) and re-upload.

Load / binding errors

Code	Meaning	What to do
4	Failed to Get Model Depth — the file's metadata is missing the input depth	Re-upload the model file so the input depth is set correctly. See Model Inference Requirements.
5	Failed to Get Bindings — binding config could not be loaded from the configuration database	Rare; usually a database connectivity issue. Check the model logs.
6	Bindings Invalid State — bindings exist but are inconsistent (e.g. an input with no tag assigned, or an output index that doesn't match the file)	Review the bindings on the Bindings tab.

Inference errors

Code	Meaning	What to do
7	Failed to Structure History — history could not be organized into the shape the model expects	Usually a data-type issue or an unexpected gap in history. Check the input tags.
8	Failed to Get Predictions — the model ran but produced no output	Often the file is incompatible with the input tensor shape. Check that the number of bindings matches the model's expected inputs.
9	Binding Prediction Index Missing — an output binding's Output Index doesn't match any output position	Reconcile output indices against the model architecture.
10	Failed to Scale Predictions — de-normalizing predictions failed	Check that output bindings have valid normalization ranges.
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
12	Thread Error — the execution thread hit an internal error	Usually resolves on the next scan cycle. If it persists, check the predict engine service logs.
13	Generic Exception — an unclassified error; the detail carries the exception	Check the model logs for the full stack trace.
999	Unlicensed — the license does not cover this model	See Licensing Problems.

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.
12	Binding Tag Bad Quality — the tag read, but the source reported poor quality	The value may be stale or unreliable. See Bad, Missing, or Frozen Tag Values.
13	Binding Tag Failed — the bound tag is in a failed state	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 (depth × sample rate). This is normal — the model starts running on its own once enough data accumulates. The window size comes from the model file; 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 enable Custom Range on the binding. 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.
6	Failed to Normalize — the normalization calculation errored (e.g. divide-by-zero from an invalid range)	Check the normalization type and range values.
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 on the binding's Configuration tab.

Data-structuring errors

Code	Meaning	What to do
7	Failed to Structure History — the binding's history could not be interpolated or organized	Often inconsistent timestamps or unexpected values in the history.
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.
10	Failed to Write Prediction — the output could not be written to the live data cache	Rare; usually a cache connectivity issue.
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
15	Binding Not in Dictionary — internal lookup miss; should not occur in normal operation	Check the model logs; report it if it persists.
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 (depth × sample rate). 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 on its Configuration tab.

"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 uploading a file with a different architecture. Reconcile the bindings on the Bindings tab to match the new input/output structure. See 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

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