Troubleshooting & FAQ

Solutions to common issues and frequently asked questions.

Installation issues

”No matching manifest for windows/amd64” on Windows Server

When running docker pull on Windows Server 2022 (or other Windows versions), you may see:

no matching manifest for windows/amd64 in the manifest list entries

Cause: Docker is running in Windows container mode, but Konnect is a Linux container image. The Konnect Docker image is built for linux/amd64 and linux/arm64 only — there is no Windows native image.

Fix — Switch Docker to Linux containers:

Docker Desktop: Right-click the Docker Desktop tray icon → “Switch to Linux containers…”

Command line:

& 'C:\Program Files\Docker\Docker\DockerCli.exe' -SwitchLinuxEngine

If you’re not using Docker Desktop, ensure WSL2 is enabled and Docker is configured to use the WSL2 backend:

# Install WSL2 if not already installed
wsl --install

# Then in Docker Desktop → Settings → General → enable "Use the WSL 2 based engine"

After switching to Linux containers, retry the pull:

docker pull ghcr.io/kyanitesolutions/konnect:beta-latest

Note: Konnect runs on Linux containers on all platforms — Windows, macOS, and Linux. You do not need a Linux server. Docker handles the virtualisation automatically.

Connection issues

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

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

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

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

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

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

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

Dashboards auto-save. If changes aren’t persisting, check browser local storage isn’t full.
Try clearing browser cache and reloading.

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.

FAQ

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?

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?

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?

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?

Any server that implements the OPC-UA specification, including Kepware, Ignition, Prosys, and open62541-based servers.

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?

In-app feedback — Click “Send Feedback” in the sidebar footer.
Website — kaisoft.ie

Next steps

Configuration → — Docker setup, LLM providers, and data connections.
System Requirements → — Check hardware and software prerequisites.