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 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?

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.

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.

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.
• 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.
• A binding shows "Bad: Expression" or "Mapping Error" (tag codes 110 / 108) → the transformation layer failed on that tag. See Expression & Value-Mapping Errors.
• 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:

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.
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.

What's Next

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