---
title: "Troubleshooting Koios"
description: "Start here when something is broken: find your symptom and jump to the right guide"
source_url: https://ai-ops.com/docs/troubleshoot/introduction
---

# Troubleshooting Koios

This is the starting point when something in Koios isn't working. Find what you're seeing in the symptom table below and jump straight to the guide that covers it. If you're not sure where to start, read [Reading Status, Quality & Errors](https://ai-ops.com/docs/troubleshoot/reading-status-and-errors.md) first — it explains the three diagnostic fields (error code, error message, error detail), the status and quality legend, and the master error-code lookup that every other article references.

## What Are You Seeing?

| Symptom | Where to go |
|---------|-------------|
| A device is **Failed** / offline, won't connect, or a **Test** connection fails | [Troubleshoot a Connection](https://ai-ops.com/docs/troubleshoot/connection.md) |
| A tag has **no value**, bad quality, a frozen value, or a read/write error | [Bad, Missing, or Frozen Tag Values](https://ai-ops.com/docs/troubleshoot/tag-values.md) |
| A **calculation tag** or **value mapping** is throwing an error | [Expression & Value-Mapping Errors](https://ai-ops.com/docs/troubleshoot/expressions-and-mapping.md) |
| A **model** or one of its **bindings** won't run, or predictions are wrong | [A Model or Binding Isn't Running](https://ai-ops.com/docs/troubleshoot/models.md) |
| **Trends are flat**, history has gaps, or data looks stale everywhere | [Data Is Stale, Frozen, or Has Gaps](https://ai-ops.com/docs/troubleshoot/stale-data.md) |
| A **service** is unhealthy, a **heartbeat** is stale, or a **CPU / memory / disk / network** alarm is active | [Service Health & Resource Alarms](https://ai-ops.com/docs/troubleshoot/services-and-alarms.md) |
| A **scan group** is failing or **overscanning** | [Service Health & Resource Alarms](https://ai-ops.com/docs/troubleshoot/services-and-alarms.md) |
| A **license** warning, invalid license, or **Unlicensed (999)** on a device / tag / model | [Licensing Problems](https://ai-ops.com/docs/troubleshoot/licensing.md) |
| The **server won't load** or the container won't start | [Server Won't Start](https://ai-ops.com/docs/troubleshoot/server-startup.md) |
| You've fixed nothing yet and need to **file a support ticket** | [Collecting Diagnostics for Support](https://ai-ops.com/docs/troubleshoot/collecting-diagnostics.md) |

## Work Down the Stack

Koios processes data in layers. A failure almost always lives at the layer where you see it, or one layer below it. When you troubleshoot, start where the symptom appears and work **downward** until the errors stop pointing further down.

```text
  Layer 5   Platform      services, heartbeats, CPU / memory / disk / network, license
     ▲
  Layer 4   Inference     models run on collected + processed data
     ▲
  Layer 3   Transformation expressions and value mappings turn raw reads into usable values
     ▲
  Layer 2   Collection    the datacollector reads tag values on each scan cycle
     ▲
  Layer 1   Connection    a device holds the link to the industrial endpoint
```

The chain of causation runs bottom-up: a **model** fails because one of its **binding tags** is bad; that **tag** is bad because its parent **device** is down; that **device** is down because of a **network or certificate** problem. Fixing the lowest broken layer clears everything above it automatically — errors self-heal on the next successful scan or inference cycle.

> [!TIP] Follow the error down, not up
> When every input on a model shows "Binding Tag Failed" or "Parent Failed", stop looking at the model. Open the failing tag, then its device. The real fix is at the bottom of the stack, and it cascades back up on its own.

A few concrete chains you'll see:

- **All tags on one device show "Parent Failed" (tag code 1)** → the device itself failed (connection layer). Fix the device; the tags clear. See [Troubleshoot a Connection](https://ai-ops.com/docs/troubleshoot/connection.md).
- **A model shows "Binding Tag Bad Quality" or "Binding Tag Failed" (binding codes 12 / 13)** → the bound tag has a read problem (collection layer). Fix the tag. See [Bad, Missing, or Frozen Tag Values](https://ai-ops.com/docs/troubleshoot/tag-values.md).
- **A binding shows "Bad: Expression" or "Mapping Error" (tag codes 110 / 108)** → the transformation layer failed on that tag. See [Expression & Value-Mapping Errors](https://ai-ops.com/docs/troubleshoot/expressions-and-mapping.md).
- **A binding shows "Upstream Model Failure" (binding code 17)** → the input tag is written by another model that is itself failing. Fix the upstream model first.

## Reading the System Alerts Banner

The alerts panel in the top bar aggregates every active problem across the platform. Each alert category maps to one troubleshooting guide — use it as a shortcut to the right layer:

| Alert | What it means | Where to go |
|-------|---------------|-------------|
| **No License Found** / **License Invalid** / **License Grace Period** | Licensed functionality may be limited, or your license is expiring | [Licensing Problems](https://ai-ops.com/docs/troubleshoot/licensing.md) |
| **N Failed Devices** | One or more devices failed to connect | [Troubleshoot a Connection](https://ai-ops.com/docs/troubleshoot/connection.md) |
| **N Failed Tags** | One or more tags are in a failed state | [Bad, Missing, or Frozen Tag Values](https://ai-ops.com/docs/troubleshoot/tag-values.md) |
| **N Failed Models** | One or more AI models have failed | [A Model or Binding Isn't Running](https://ai-ops.com/docs/troubleshoot/models.md) |
| **N Failed Scan Groups** | One or more scan groups have failed | [Service Health & Resource Alarms](https://ai-ops.com/docs/troubleshoot/services-and-alarms.md) |
| **N Unhealthy Services** | A background service is not running | [Service Health & Resource Alarms](https://ai-ops.com/docs/troubleshoot/services-and-alarms.md) |
| **N Performance Alarms** | A CPU, Memory, Disk, or Network threshold was crossed | [Service Health & Resource Alarms](https://ai-ops.com/docs/troubleshoot/services-and-alarms.md) |

> [!NOTE] Failed counts are cascades, not separate problems
> A single failed device inflates the failed-tag and failed-model counts too, because every tag on that device and every model bound to those tags fails with it. Clear the device alert first and watch the tag and model counts fall on their own.

## The Universal Recovery Path

Whatever the layer, the same loop applies. Errors are not sticky — they clear on the next successful cycle, so your job is to fix the underlying cause, not to dismiss the error:

1. Read the **error message** and **error detail** on the failed entity to get the specifics.
2. Open the entity's **Logs** tab and set the log level to **Debug** for maximum detail. See [System Logs](https://ai-ops.com/docs/system/logs.md).
3. Work **down** the stack — if the error points at a lower layer (parent device, binding tag, upstream model), go fix that first.
4. Correct the configuration or connection, or use the **Test** button to confirm the fix in isolation.
5. As a last resort, toggle the entity off and on with the **Enabled** switch.

For the full field-by-field explainer, the status and quality color legend, and the "why is this stuck?" checklist, see [Reading Status, Quality & Errors](https://ai-ops.com/docs/troubleshoot/reading-status-and-errors.md).

## What's Next

- [Reading Status, Quality & Errors](https://ai-ops.com/docs/troubleshoot/reading-status-and-errors.md) — the shared reference: three diagnostic fields, status and quality legend, stuck checklist, master code lookup
- [Troubleshoot a Connection](https://ai-ops.com/docs/troubleshoot/connection.md) — layer 1: device and tag connectivity, certificates, network, Test
- [Bad, Missing, or Frozen Tag Values](https://ai-ops.com/docs/troubleshoot/tag-values.md) — layer 2: bad quality, no value, read/write, configuration
- [Expression & Value-Mapping Errors](https://ai-ops.com/docs/troubleshoot/expressions-and-mapping.md) — layer 3: transformation errors
- [A Model or Binding Isn't Running](https://ai-ops.com/docs/troubleshoot/models.md) — layer 4: model and binding inference
- [Data Is Stale, Frozen, or Has Gaps](https://ai-ops.com/docs/troubleshoot/stale-data.md) — cross-cutting: historization and trends gaps
- [Service Health & Resource Alarms](https://ai-ops.com/docs/troubleshoot/services-and-alarms.md) — layer 5: services, heartbeats, resource alarms, scan groups
- [Licensing Problems](https://ai-ops.com/docs/troubleshoot/licensing.md) — license state and Unlicensed (999)
- [Server Won't Start](https://ai-ops.com/docs/troubleshoot/server-startup.md) — container, logs, and restart during an outage
- [Collecting Diagnostics for Support](https://ai-ops.com/docs/troubleshoot/collecting-diagnostics.md) — what to gather before opening a ticket
- [System Logs](https://ai-ops.com/docs/system/logs.md) — set the Debug log level and stream service logs