---
title: "Collecting Diagnostics for Support"
description: "Gather the right logs and details before opening a support case"
source_url: https://ai-ops.com/docs/troubleshoot/collecting-diagnostics
---

# Collecting Diagnostics for Support

When you open a support case, the fastest resolutions come from tickets that already include the version, the logs, and the exact error. This page is the checklist to run through before you reach out. Other troubleshooting pages link here instead of re-describing how to set Debug or dump logs.

> [!TIP] Gather everything in one pass
> Work top to bottom and collect each item into a single folder or message. A ticket with all five items attached skips a full round-trip of back-and-forth questions.

---

## 1. Koios version

Support needs to know exactly which build you are running. Find the version in the interface under **System**, or read it from the container:

```bash
docker exec koios cat /var/www/koios/VERSION
```

If you recently upgraded, note the version you upgraded **from** as well — many issues trace back to the upgrade step.

---

## 2. Container status

Confirm whether the `koios` container is healthy or restart-looping. On the machine running Koios (or over SSH):

```bash
docker ps
```

Find the `koios` container. A healthy server shows a status like `Up 2 minutes (healthy)`. A status that keeps resetting to `Restarting`, or shows `(unhealthy)`, means the server is failing to start — capture that too. If Koios runs as a service, check it directly:

```bash
sudo systemctl status docker.koios
```

> [!NOTE] If the server won
> A container stuck on `Restarting`, or a sign-in screen frozen on "Starting up...", is an outage, not a per-entity fault. Follow [Server Won't Start](https://ai-ops.com/docs/troubleshoot/server-startup.md) — it walks through the startup logs and recovery — then attach what you find here.

---

## 3. Logs

Logs are where the failure actually reports itself. There are two useful sources.

### Set Debug and capture the affected service

Before reproducing the problem, raise the log level of the relevant service to **Debug** for maximum detail, reproduce the issue, then stream or download the log. This is all done from the interface — see [Logs](https://ai-ops.com/docs/system/logs.md) for selecting a service, setting the level, streaming live output, and downloading archived log files. Return the service to **Info** or **Warning** afterward to reduce noise.

> [!TIP] Match the service to the symptom
> Set Debug on the service that owns the failing entity: the data collector for device and tag reads, the predict engine for models and bindings, the expression or mapping service for value transforms. Debug reverts on its own after the configured timer, so you won't leave a service verbose by accident.

### Dump the container logs to a file

For startup problems or when the interface isn't reachable, write the container's log stream straight to a file you can attach:

```bash
docker logs --tail 500 koios > koios-diagnostics.log
```

To read a specific service's log file from inside the container instead:

```bash
docker exec koios tail -n 200 /var/www/koios/logs/services/django.log
```

When reading through a dump, scroll to the end and read upward to the first error or traceback — the last error before a restart is almost always the real cause.

---

## 4. The error Code, Message, and Detail

Every failing entity surfaces three diagnostic fields — a numeric **Code**, a short **Message**, and a longer **Detail**. Copy all three verbatim from the affected device, tag, model, binding, or scan group. The code alone tells support which layer failed and which service log to read.

For what each field means, the full status and quality legend, the auto-clear behavior, and the master code lookup, see [Reading Status, Quality & Errors](https://ai-ops.com/docs/troubleshoot/reading-status-and-errors.md). A few of the most common codes to have on hand when you write the ticket:

| Entity | Code | Meaning |
|--------|------|---------|
| Device | 1 — Failed To Connect | The device could not reach the industrial endpoint |
| Tag | 104 — Bad: Configuration Error | The tag has a bad address, type, or settings |
| Tag | 105 — Bad: No Value | No value was returned for the tag |
| Binding | 1 — Not Enough Historical Depth | The bound tag lacks enough history for the model's lookback |
| Model | 3 — Failed To Parse File | The model file is invalid or corrupt |
| Scan group | 1 — Overscan | Execution could not keep up with the configured scan rate |
| Any | 999 — Unlicensed | The entity is not covered by a valid license |

Include the entity's name and status alongside the three fields so support can locate it.

---

## 5. A recent backup

If the issue may require restoring or inspecting configuration and data, take a backup before you make any changes, and note whether one already exists from before the problem started. See [Backup & Restore](https://ai-ops.com/docs/system/backup.md) for how to create and download one.

> [!WARNING] Back up before you change anything
> Do not delete data, force a container past a failing startup step, or downgrade the version to "try something" before support has looked. A backup taken now preserves the failing state so the cause can still be diagnosed.

---

## Diagnostics checklist

| Item | Where to get it |
|------|-----------------|
| Koios version (and prior version if upgraded) | System page, or `docker exec koios cat /var/www/koios/VERSION` |
| Container status | `docker ps` / `systemctl status docker.koios` |
| Service log at Debug for the failing service | [Logs](https://ai-ops.com/docs/system/logs.md) |
| Container log dump (`koios-diagnostics.log`) | `docker logs --tail 500 koios > koios-diagnostics.log` |
| Error Code, Message, and Detail from the affected entity | The entity's detail panel — see [Reading Status, Quality & Errors](https://ai-ops.com/docs/troubleshoot/reading-status-and-errors.md) |
| A recent backup | [Backup & Restore](https://ai-ops.com/docs/system/backup.md) |

---

## What's Next

- [Reading Status, Quality & Errors](https://ai-ops.com/docs/troubleshoot/reading-status-and-errors.md): the three diagnostic fields, the status and quality legend, and the master error-code lookup
- [Troubleshooting Koios](https://ai-ops.com/docs/troubleshoot/introduction.md): the symptom router for finding the right layer to investigate
- [Server Won't Start](https://ai-ops.com/docs/troubleshoot/server-startup.md): recover a container that won't finish starting
- [Logs](https://ai-ops.com/docs/system/logs.md): set the Debug log level, stream live output, and download archived log files
- [Backup & Restore](https://ai-ops.com/docs/system/backup.md): create a backup to attach or to protect the failing state