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 every item attached skips a full round-trip of back-and-forth questions.

1. Koios version

Support needs to know exactly which build you are running. In the interface, open the Version card on System > Overview and click it — the popover lists the individual version of each internal service and the release date. Include that whole list in the ticket, not just the platform version.

From the container, read it out of the environment file:

docker exec koios grep KOIOS_VERSION /var/www/koios/environment/.env

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	2 — No File Found	No model file is loaded, or the file present would not load
Model	6 — Bindings Invalid State	The model's configuration failed the load-time check; the detail names the reason
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.

6. The request ID and audit record

If the problem is a change that didn't take effect, or an action that was denied, the request ID is the highest-signal evidence you can send.

Reproduce the failing action with your browser's developer tools open, on the Network tab.
Select the failing request and copy the X-Request-Id value from its response headers. Every response carries one.
Open System > Audit Log and narrow the trail to the failing action — filter by Actor and by the Time range around your reproduction, plus Action or Outcome if you know them. The request ID is neither a column nor a search term: it appears when you open an individual record's detail panel, which also shows the source IP and user agent.
Export the filtered view as CSV or JSON, then search the export for the request ID to pin down the exact record. Attach the export alongside the ID.

See Audit Log for filtering and exporting.

Diagnostics checklist

Item	Where to get it
Koios version, per-service versions, and prior version if upgraded	The Version card on System > Overview (click to expand), or `docker exec koios grep KOIOS_VERSION /var/www/koios/environment/.env`
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
Request ID of the failing request, and the matching audit record	`X-Request-Id` response header (browser Network tab) + an export from Audit Log
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
Audit Log: filter the trail, open a record's detail panel, and export the filtered view
Backup & Restore: create a backup to attach or to protect the failing state

Server Won't Start Updating Koios