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.

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:

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):

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:

sudo systemctl status docker.koios

If the server won't come up at all

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

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:

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

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

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. 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 for how to create and download one.

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
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
A recent backup	Backup & Restore

What's Next

Reading Status, Quality & Errors: the three diagnostic fields, the status and quality legend, and the master error-code lookup
Troubleshooting Koios: the symptom router for finding the right layer to investigate
Server Won't Start: recover a container that won't finish starting
Logs: set the Debug log level, stream live output, and download archived log files
Backup & Restore: create a backup to attach or to protect the failing state

Server Won't Start Updating Koios