Skip to content

troubleshooting.md

Latest commit

 

History

History
141 lines (93 loc) · 3.58 KB

troubleshooting.md

File metadata and controls

141 lines (93 loc) · 3.58 KB
Raw

Troubleshooting

The CLI exits immediately with "Invalid host, please specify a protocol"

Cause: --host was given without a protocol prefix.

Fix: Always include ws:// or wss://:

# wrong
hivemind-cli --access-key <key> --host 192.168.1.10

# correct
hivemind-cli --access-key <key> --host wss://192.168.1.10

Cannot connect: connection refused or timeout

Check the port. HiveMind-core defaults to 5678. If your server uses a different port, pass --port:

hivemind-cli --access-key <key> --host ws://192.168.1.10 --port 8181

Check the host is reachable. Ping the server and verify HiveMind-core is running:

ping 192.168.1.10
ssh user@192.168.1.10 -- systemctl status hivemind

Check the firewall. Port 5678 (or your custom port) must be open for inbound TCP on the server.

SSL / TLS errors on wss://

Certificate verification failure. If HiveMind-core uses a self-signed certificate, add --self-signed:

hivemind-cli --access-key <key> --host wss://192.168.1.10 --self-signed

Without this flag, the underlying WebSocket library rejects certificates that are not signed by a trusted CA.

Hostname mismatch. If the certificate is issued for a hostname and you are connecting by IP, either:

  • Connect by hostname: wss://myhive.local
  • Or use --self-signed (which disables hostname verification as well as CA verification).

Authentication failure

Wrong access key or password. Verify that the values printed by hivemind-core add-client are copied exactly (no trailing spaces, no quotes).

Client not registered. The access key must correspond to a client registered on the hive node you are connecting to. Keys are not portable across nodes.

Re-issue credentials:

hivemind-core add-client

Then reconnect with the new key and password.

No response from the hive

The hive is connected but not answering. This usually means:

  • The utterance was not matched by any skill. Try a basic built-in utterance such as what time is it.
  • The skill handling the utterance crashed on the server side. Check HiveMind-core logs on the server.
  • The speak message is not being routed back. Confirm that the hive node's bridge is configured to relay speak messages to clients.

Curses rendering issues over SSH

Garbled display or curses errors. This is usually a TERM environment variable mismatch.

TERM=xterm-256color hivemind-cli --access-key <key> --host ws://127.0.0.1

Fallback: Use --no-curses for a plain stdin/stdout interface that works in any terminal:

hivemind-cli --access-key <key> --host ws://127.0.0.1 --no-curses

curses not available. If curses is not importable (some minimal Python installs), the library prints a warning at import time:

WARNING: curses interface not available

In this case JarbasCursesTerminal is aliased to JarbasCliTerminal automatically. The --no-curses flag is redundant but harmless.

Local-network scan finds no nodes

Cause: The hive node does not have presence/discovery enabled, or UDP broadcast is blocked on the network.

Fix: Specify --host explicitly instead of relying on discovery:

hivemind-cli --access-key <key> --host ws://192.168.1.10

"Scan aborted and host not specified, exiting" (exit code 2)

You answered n (or anything not starting with y) when asked whether to scan. Either re-run with --host, or run again and answer y to the scan prompt.

← Development & Testing · Home