Symptom, cause, fix — for the agent, the dashboard, and the API. Error texts below are quoted exactly as you'll see them.
Cause: Ollama isn't running, or it listens on a different port.
Fix: start Ollama and confirm it answers with ollama list. If it runs on a non-standard port, launch the agent with --port <n>.
Cause: a --url value starts with ws://.
Fix: only encrypted wss:// URLs are accepted — the agent refuses to connect over plaintext.
Cause: the automatic Java install requires a restart before Windows picks up the new runtime.
Fix: restart your computer after the Java installer finishes, then run mealissa-llm-agent.bat again. Details in the Install guide, step 6.
Cause: the cloud requires the model's parameter count, and your Ollama didn't report it (the agent also warns at startup: [warn] Could not retrieve param_count).
Fix: update Ollama to a current version, re-pull the model (ollama pull <model>), and restart the agent.
Cause: the key was mistyped, the trial expired, or the license was deactivated. The server refuses the connection — or closes existing ones when a license lapses mid-session.
Fix: check the key's status in the cloud console (Licenses view), or test it directly:
curl -s https://mealissa.com/cloud/api/license/validate \
-H "Authorization: Bearer <your-license-key>"Returns true for a valid key, false otherwise. See Getting a license for a new key.
Cause: the agent isn't connected, or you're looking at a different group than the one the agent joined.
Fix: in the agent's terminal, type status — it prints the group and whether each server connection is connected or disconnected. The agent reconnects automatically with backoff, so a briefly dropped node reappears on its own; if it doesn't, restart the agent and watch for one of the registration errors above.
Cause: missing or wrong Authorization: Bearer header.
Fix: send your license key as the Bearer token; validate it with the curl above.
Cause: no online node has that ID — the agent is down, or the ID in your URL is wrong.
Fix: copy the exact node ID from the dashboard, and confirm the node shows as online.
Cause: every node in the group is offline, or the group name differs from what the agents joined.
Fix: group names are exact — check the dashboard for the group's spelling and make sure at least one agent is running.
Cause: the model didn't answer within the request timeout (default 600 s) — common for large models on modest hardware.
Fix: use a smaller model, or raise the timeout value in the request body and your SDK client's own timeout. See Connecting via the Claude SDK.
The agent stores its saved settings — the encrypted license key and your last group — in ~/.mealissa/agent.json. Delete that file and the next launch asks everything again from scratch:
del %USERPROFILE%\.mealissa\agent.jsonrm ~/.mealissa/agent.jsonThe Install guide takes you from a fresh machine to a registered node in minutes.