---
title: "A Model or Binding Isn't Running"
description: "Work down from a failed model through its bindings to the tags and devices feeding it"
source_url: https://ai-ops.com/docs/troubleshoot/models
---

# 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](https://ai-ops.com/docs/troubleshoot/reading-status-and-errors.md). 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.

> [!TIP] 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:

1. **Validate bindings** — each input tag is assigned, enabled, and running
2. **Query history** — fetch historical data from the time-series database
3. **Preprocess** — interpolate, check ranges, normalize, assemble the input tensor
4. **Run inference** — execute the ONNX or TFLite model
5. **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](https://ai-ops.com/docs/models/inference-requirements.md).

## 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](https://ai-ops.com/docs/models/inference-requirements.md). |
| 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](https://ai-ops.com/docs/troubleshoot/licensing.md). |

## 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](https://ai-ops.com/docs/troubleshoot/tag-values.md). |
| 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](https://ai-ops.com/docs/troubleshoot/tag-values.md). |
| 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). |

> [!WARNING] 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](https://ai-ops.com/docs/devices/on-demand-scanning.md) for the batch-window mechanics and [On-Demand Inference](https://ai-ops.com/docs/models/on-demand-inference.md) 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. |

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

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](https://ai-ops.com/docs/troubleshoot/stale-data.md).

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

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

## 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](https://ai-ops.com/docs/troubleshoot/connection.md)), then confirm the **On-Demand Timeout** covers the batch window plus device read time. See [On-Demand Scanning](https://ai-ops.com/docs/devices/on-demand-scanning.md).

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

### 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](https://ai-ops.com/docs/troubleshoot/services-and-alarms.md).

## If a Model Stays Stuck

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

1. Read the **Bindings** tab for per-binding errors; they are more actionable than the model-level error.
2. Set the model's log level to **Debug** on the [Logs](https://ai-ops.com/docs/system/logs.md) tab and watch each pipeline stage.
3. Confirm every input tag is **enabled and running** — one disabled or failed tag blocks the whole model.
4. Check the tag devices — a down device fails all its tags, which cascades to every model using them.
5. 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](https://ai-ops.com/docs/troubleshoot/collecting-diagnostics.md).

## What's Next

- [Reading Status, Quality & Errors](https://ai-ops.com/docs/troubleshoot/reading-status-and-errors.md) — the shared error-field reference, status/quality legend, and stuck-error checklist
- [Model Inference Requirements](https://ai-ops.com/docs/models/inference-requirements.md) — input/output tensor shapes, input depth, normalization
- [On-Demand Inference](https://ai-ops.com/docs/models/on-demand-inference.md) — model-side on-demand cycle and timeout
- [On-Demand Scanning](https://ai-ops.com/docs/devices/on-demand-scanning.md) — device-side freshness and batch-window latency
- [Bad, Missing, or Frozen Tag Values](https://ai-ops.com/docs/troubleshoot/tag-values.md) — when a binding's tag is the problem
- [Data Is Stale, Frozen, or Has Gaps](https://ai-ops.com/docs/troubleshoot/stale-data.md) — when history is stale but the tag is live
- [Troubleshoot a Connection](https://ai-ops.com/docs/troubleshoot/connection.md) — when the device feeding a tag is unreachable
- [Service Health & Resource Alarms](https://ai-ops.com/docs/troubleshoot/services-and-alarms.md) — scan-group and predict-engine health
- [Licensing Problems](https://ai-ops.com/docs/troubleshoot/licensing.md) — the Unlicensed (999) code
- [Collecting Diagnostics for Support](https://ai-ops.com/docs/troubleshoot/collecting-diagnostics.md) — what to gather before a ticket