Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Troubleshooting

taktwerk run logs to stderr (RUST_LOG filters, default info; under systemd journalctl -u <unit>, on a device taktwerk device logs), prints a summary when it stops and exits non-zero after a model or connector failure. taktwerk check lists every problem it finds, not only the first.

Loading and checking

messagecause and fix
GLIBC_2.xx not foundthe binary or a model library was linked against a newer glibc than the target’s: cross-build against the target’s glibc or older
a load error naming lib/<arch> or the descriptorthe raw package has no library for this machine’s architecture (uname -m), or the descriptor does not parse
an FMU refused, naming the platforms it hasno binary under binaries/<platform>/ for this architecture (Platform binaries)
abi.confirmed is false: …a proposed descriptor: review it (Workflow) and set abi.confirmed = true
the library reports … but dimension … is bound to …the project’s dims differ from the lengths the library reports at init
writes N node(s): set writes = "on" …an opcua-client or rest map writes and the connector has no writes: set "dry-run" or "on" (Dry run)
a … connector exchanges values in wall time; run it in real time …an opcua-client or rest connector in a run with --speed: add --no-connectors, or run in real time
an unknown keythe project, scenario and campaign files refuse keys they do not know: a typo, or a key of a newer version

Starting

messagecause and fix
cannot put the cycle thread on … pthread_setschedparam failed …[engine.realtime] needs LimitRTPRIO ≥ the priority, or CAP_SYS_NICE (Real time)
mlockall(…) failed …lock_memory needs LimitMEMLOCK=infinity, or CAP_IPC_LOCK
cpu = N is past the affinity maskthe CPU does not exist or the cgroup does not allow it
Address already in useanother process holds the port: another engine, a PLC’s own OPC UA server on 4840; pick another endpoint or listen
an opcua-client session refused, listing nodesa mapped node is missing, of another type or shape, or not writable where the connector writes; check --live prints the same per node
a rest bind refused, listing mappingsa pointer finds nothing in a GET answer, or the value does not fit its signal

Running

symptomcause and fix
taktwerk.status is 2, taktwerk.stale countsan external input is older than its max_age_ms or was never written: the connector lost its server, a read returns a bad status, or a mapping rejects the value (out of min/max, unchanged longer than max_unchanged_s); the engine log names it once, events.csv has a stale event, taktwerk engine status lists stale_inputs
taktwerk.overruns countsticks take longer than tick_ms, or the thread wakes late: measure the mean and longest tick in the run summary, use [engine.realtime] and a dedicated CPU, or a longer tick
the heartbeat stops, outputs frozenstale inputs (above); an instance down with on_error = "hold" or "safe" (taktwerk.status 4, taktwerk.instance.<id>.state and code say which and why); or the engine stopped: a model returned an error (fault event, the code in the log)
a PLC keeps old valuesthe write gate is closed: gate_open is false, the gate event says why
a tunable write has no effectit was refused (type, length, text capacity, range): refused … in events.csv, the writer got an error (OPC UA BadOutOfRange, BadUserAccessDenied for a read-only identity)
a write to the http API is refusedit needs writes = true (--http-writes) and Authorization: Bearer <token>
403 from the http API or servethe request’s Host is not loopback or localhost, or the browser marked it cross-site: open the URL as printed
a recorder’s rows_dropped countsthe file sink fell a ring behind: a slow disk; raise buffer_s, record fewer signals or a larger every
a gap in a pulled recordtaktwerk record was away longer than the engine’s buffer_s

Devices

messagecause and fix
the host key of … is …, not the pinned …: refusing to connectthe device’s key changed (reinstalled, or another machine at that address): check the new key on the device and pin it with device verify --accept-host-key <fingerprint>
no host key is pinned for …verify the device first
the device's agent speaks interface N, this host Mthe taktwerk on the device speaks another agent interface than the host’s: use a host whose version matches
unit-runningactivate, rollback and a deploy refuse while the bundle’s unit runs: stop it first
arch-mismatchthe release was built for another architecture than the device’s
ci-refused--yes is refused while CI is set
no journal lines from logsthe login user is not in the systemd-journal group

The agent’s error codes are listed in Agent.