Troubleshooting

Troubleshooting

Install and start

Symptom	Cause	Fix
ModuleNotFoundError	virtualenv not active	activate .venv, reinstall requirements
no such table	migration not run	cd backend && python migrate.py up
settings.json not found	config step skipped	cp backend/settings.example.json backend/settings.json
Port 8766 in use	previous instance running	change --port, or stop the old process
UnicodeEncodeError on Windows	console is cp1252	set PYTHONIOENCODING=utf-8

Reading the health verdict

curl http://127.0.0.1:8766/api/system/health

The response lists all 14 checks by name with a status each. Read it before changing anything — and note that YELLOW is not a failure:

Verdict	Meaning	Action
GREEN	every subsystem reachable	none
YELLOW	up and running; something optional is absent	read the message — it names the remedy
RED	the House itself is faulty	fix the named check; ok is false

Two YELLOWs are normal on a fresh install and resolve themselves:

• ollama — no local model runtime at … — you have not started a model runtime yet, or you intend to use a cloud connection instead. Both are supported states.
• SELF.md — not yet generated — the backend writes this file for itself at boot; it appears the first time the server starts.

A RED check is different in kind: a missing UI file, a module that will not import, a corrupt database, or a broken audit chain. Those are the only conditions that make ok false.

Models

Symptom	Cause	Fix
Calls hang or time out	Ollama not running	ollama serve, then ollama list
model not found	tag not pulled	ollama pull <tag>, and check settings.json matches
Tool calls produce malformed JSON	model too small	use ≥7B, or route execution to a code-tuned model
Long tasks fail oddly mid-run	context ceiling exceeded	raise --ctx-size on the server, or use the compact prompt
Cloud provider 401	key missing or wrong api_type	check .env and /api/connections/{id}/ping

A small model failing at execution is the system working — the governance gate is rejecting malformed output rather than accepting nonsense. See Choosing a Model.

Docker

Symptom	Cause	Fix
Backend cannot reach Ollama	used localhost inside the container	it is http://ollama:11434
Memory gone after restart	down -v deleted the volume	see Docker
Healthcheck never turns healthy	backend failed to boot	docker compose logs skynetclaw

The council behaves oddly

Symptom	Likely cause
No memory of prior sessions	fresh database — the House has no history yet (First Run)
Verdicts keep getting rejected	Governance Engine is doing its job — the forecast lacks an invalidation condition, or a claim lacks evidence
A tool call is refused	the PRE_ACT gate denied it — check the governance log (Security Model)
Recall returns nothing useful	too few graded sessions; recall weights justified memories (Recall Quality)

Tests

cd backend && python -m pytest -q       # expect 601 passed

A failure here on a clean checkout is a bug worth reporting — please include the OS, Python version, and the failing output.

→ Next: FAQ