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

Health is not GREEN

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

The response lists all 14 checks by name with a status each. A non-GREEN check names exactly what is missing — read it before changing anything.

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