Troubleshooting & FAQ
Solutions to common issues and frequently asked questions.
Connection issues
Section titled “Connection issues”Kaisoft won’t start
Section titled “Kaisoft won’t start”| Symptom | Solution |
|---|---|
| Container exits immediately | Check Docker logs: docker logs kaisoft. If Kai does not respond, check that an AI provider key is saved under Settings → AI Providers. |
| 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 Kaisoft’s certificate. Check your server’s certificate management. |
Kai issues
Section titled “Kai issues”Kai shows a lock or “No License Found”
Section titled “Kai shows a lock or “No License Found””Kai requires an active license. Go to License in the left sidebar to check your status:
- No license — upload the
.jwtfile you received from Kaisoft. - Expired — request a new license and upload it; activation is immediate.
See Licensing. Dashboards, data sources, and reports keep working while Kai is locked.
Kai doesn’t respond
Section titled “Kai doesn’t respond”| Symptom | Solution |
|---|---|
| ”No response” or spinning | Check that at least one AI provider key is configured under Settings → AI Providers. |
| ”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. Kaisoft auto-reconnects, but frequent drops indicate network issues. |
Can I use Kaisoft without an internet connection?
Section titled “Can I use Kaisoft 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 Kaisoft store my data?
Section titled “Does Kaisoft store my data?”Kaisoft 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 Kaisoft simultaneously?
Section titled “Can multiple users access Kaisoft simultaneously?”Yes. Kaisoft 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 Kaisoft?
Section titled “How do I update Kaisoft?”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
- GitHub — github.com/KyaniteSolutions
Next steps
Section titled “Next steps”- Configuration → — Review app settings and providers.
- System Requirements → — Check hardware and software prerequisites.