Troubleshooting & FAQ
Solutions to common issues and frequently asked questions.
Connection issues
Section titled “Connection issues”Konnect won’t start
Section titled “Konnect won’t start”| Symptom | Solution |
|---|---|
| Container exits immediately | Check Docker logs: docker logs konnect. Ensure the container has sufficient memory and the data volume is mounted correctly. |
| Port already in use | Change the host port: -p 9090:7080 instead of -p 8080:7080. |
| Out of memory | Ensure at least 4 GB RAM is available. Check with docker stats. |
Cannot connect to a database
Section titled “Cannot connect to a database”| Symptom | Solution |
|---|---|
| ”Connection refused” | Verify the database is running and the host/port are correct. If the database is on your host machine, use host.docker.internal instead of localhost. |
| ”Authentication failed” | Double-check the username and password. Ensure the user has access to the specified database. |
| ”Database does not exist” | Verify the database name is spelled correctly. |
| ”Timeout” | Check network connectivity. Ensure firewalls allow traffic on the database port. |
Cannot connect to MQTT broker
Section titled “Cannot connect to MQTT broker”| Symptom | Solution |
|---|---|
| ”Connection refused” | Verify the broker URL and port. Ensure the broker is running. |
| ”Not authorised” | Check username and password. Some brokers require authentication. |
| ”No messages received” | Verify your topic subscription pattern. Use # to subscribe to all topics for testing. |
Cannot connect to OPC-UA server
Section titled “Cannot connect to OPC-UA server”| Symptom | Solution |
|---|---|
| ”Connection refused” | Verify the endpoint URL. Ensure the OPC-UA server is running and accessible. |
| ”Security policy error” | Try setting security mode to None for initial testing. |
| ”Certificate rejected” | The server may need to trust Konnect’s certificate. Check your server’s certificate management. |
AI assistant issues
Section titled “AI assistant issues”Kai doesn’t respond
Section titled “Kai doesn’t respond”| Symptom | Solution |
|---|---|
| ”No response” or spinning | Check that you’ve entered a valid LLM API key in the chat interface. |
| ”API key invalid” | Verify your API key is correct and has not expired. |
| ”Rate limit exceeded” | Wait a few minutes and try again. Consider switching to a different LLM provider. |
Kai gives incorrect results
Section titled “Kai gives incorrect results”- Be more specific — Include table names, time ranges, and column names in your question.
- Check data source connections — Ensure the relevant database is connected and online.
- Try rephrasing — Different wording can produce better results.
- Switch providers — Different LLM providers may handle certain queries better.
Dashboard issues
Section titled “Dashboard issues”Charts not displaying
Section titled “Charts not displaying”| Symptom | Solution |
|---|---|
| Empty chart area | Verify the data source is connected and has data in the queried time range. |
| ”No data” message | Check that the table or topic exists and contains recent data. |
| Chart shows wrong data | Verify the correct database is selected. Ask Kai to clarify which data source it queried. |
Dashboard not saving
Section titled “Dashboard not saving”- Dashboards auto-save. If changes aren’t persisting, check browser local storage isn’t full.
- Try clearing browser cache and reloading.
Performance issues
Section titled “Performance issues”| Symptom | Solution |
|---|---|
| Slow queries | Add LIMIT to large queries. Check database indexing. |
| High memory usage | Reduce the number of active MQTT subscriptions. Close unused dashboard tabs. |
| WebSocket disconnections | Check network stability. Konnect auto-reconnects, but frequent drops indicate network issues. |
Can I use Konnect without an internet connection?
Section titled “Can I use Konnect without an internet connection?”Yes, if you use Ollama as your LLM provider. Ollama runs models locally on your machine. All other providers (Groq, OpenAI, Anthropic) require internet access.
Does Konnect store my data?
Section titled “Does Konnect store my data?”Konnect does not copy or store your source data. It queries your databases and brokers in real time. Dashboard configurations and chat history are stored locally in the browser.
Can multiple users access Konnect simultaneously?
Section titled “Can multiple users access Konnect simultaneously?”Yes. Konnect serves a web application that multiple users can access from different browsers. Each user has their own independent session, dashboards, and chat history.
Which MQTT brokers are supported?
Section titled “Which MQTT brokers are supported?”Any broker that supports MQTT 3.1.1 or 5.0, including EMQX, Mosquitto, HiveMQ, and AWS IoT Core.
Which OPC-UA servers are supported?
Section titled “Which OPC-UA servers are supported?”Any server that implements the OPC-UA specification, including Kepware, Ignition, Prosys, and open62541-based servers.
How do I update Konnect?
Section titled “How do I update Konnect?”Pull the latest image and restart the container. See the Installation guide for step-by-step instructions.
Where can I get help?
Section titled “Where can I get help?”- In-app feedback — Click “Send Feedback” in the sidebar footer.
- Website — kaisoft.ie
Next steps
Section titled “Next steps”- Configuration → — Docker setup, LLM providers, and data connections.
- System Requirements → — Check hardware and software prerequisites.