Docs / Guides
Platform alarms and troubleshooting
What each platform alarm means, and what to do when answers or data look wrong.
Platform alarms
A platform alarm is a problem with BooleX itself, not with the plant. It shows as a red banner under the top bar ("Platform: … Timestamps may be unreliable until it clears.") and in GET /api/health. Raising and clearing are audited.
| Alarm | Means | Do this |
|---|---|---|
| Clock offset | The edge PC's clock is more than 100 ms from the site time source, or the time source did not answer | Check BOOLE_TIME_SOURCE and the NTP service on the host; keep the PLCs on the same source |
| OPC UA certificate | The server's certificate is untrusted, expired or revoked, or the server refused BooleX's | Put the server's (or its CA's) certificate in the trust_dir named in site.yaml opcua, and add BooleX's application certificate to the server's trusted clients |
| Peer not answering | High availability: the other edge PC's agent does not answer | Check the HA link; if both PCs became active, follow High availability |
| Replication | High availability: the standby is not streaming, or is more than 60 s behind | Check the HA link and the primary's store |
Common problems
| You see | Likely reason | Do this |
|---|---|---|
| "No language model is configured" | No deploy/config/llm.json, or the model server is not running | make up PROFILES=,ollama && make model; the evidence card and sources still work without it |
| The assistant does not start: a cloud endpoint is refused | A cloud model in llm.json in the production or offline-import profile | Use a local model, or the hybrid profile with the endpoint in approved_endpoints |
| The assistant does not start: HTTPS | No TLS certificate outside development | Put cert.pem and key.pem in deploy/config/tls/ (or run make up, which makes a self-signed one) |
| The development profile is refused | customer_site: true in site.yaml | Select production or offline_import |
| No plant source supports an answer | The document, code or history is not imported | Check Knowledge gaps → knowledge health, import it, ask again. Log the gap |
| A citation says the source has changed | The code or document changed after the answer | The viewer shows the cited revision; re-import or open the newer one |
| Tags not found | The tag list and the server's address space differ | python -m ingest.validate_tags --url opc.tcp://… and fix the unmatched node IDs |
| An answer mentions a data gap | The live connection dropped for a while | Nothing: BooleX recorded the gap, reconnected, and says when evidence falls inside it. The Connectors panel shows the state |
| A code element is described as opaque | A construct the importer keeps without reading it (for example vendor-specific instructions) | Answers touching it say so; tell 4M which construct |
| The watched folder imports nothing | The share is not mounted at BOOLE_WATCH_DIR, or the file type is not supported | make logs; run python -m edge.watch_folder /watch --once in the watch service |
Logs and state
shell
make ps # every service and its health make logs # follow the logs of all services make down # stop the stack; the store and data volumes are kept