Troubleshooting

Troubleshooting

Find the symptom, then the fix. Most problems come from one of two things: a host reading a different config file than you edited, or a process still running old code.

Installing and starting

symptom	cause	fix
pip fails on memai-mcp.exe: "access is denied" or "used by another process"	a host is running a server from this venv	stop-mcp.bat, stop-admin.bat, close the hosts, install again
the server will not start after an install that reported success	the launcher was rewritten while locked; the environment is half-updated	stop everything, reinstall into the same venv, reopen the hosts
the host lists no MCP server although you added one	you edited the other host's file, or did not restart the host	check the table in Getting started, then restart the host
the server starts but the store is empty or elsewhere	MEMAI_HOME was set in a shell, not in the server's env block	move it into the config entry; see Configuration
every dashboard page answers 503	the front end was never built or downloaded	.venv/bin/python tools/install-webui.py (Windows: install.bat)
npm ci refuses to run, naming the Node version	Node is older than 22.18	upgrade Node, or let install-webui.py take the prebuilt dashboard

In a session

symptom	cause	fix
every tool call is refused with "this session has not read its memory yet"	the warm-up hold: the session was briefed and has not called pulse() or must_read()	let the agent call one of them; the hold also gives way after three refusals
the session never sees a brief	the hooks are not registered, or registered by an older version	memai-hook install --check, then memai-hook install
a write is refused with a message about a missing parameter	a parameter tag was typed wrong and its text never arrived	retype the call; do not paste the old one back
the warden never runs	it is off, not installed, or installed after this session started	Maintenance → Reminders; memai-hook install --agents; open a new session
the warden runs but never reports anything	the server is registered under a name other than memai, so the warden has no tools	register it as memai
a pulled change does not show up	the server was started before the pull	restart the host
memories land in an unexpected project	the active project was switched from the dashboard; it is machine-wide	check the top bar, or list_projects()

The store

symptom	cause	fix
a schema change reappears after the servers restarted	an older dashboard is still running and rewrote it	memai-admin --stop; the next one starts from the checkout
search misses a memory you know is there	it is untagged and the query did not use its exact wording	add tags; the Health view lists untagged memories
Acme/x and acme/x show as two domains	the casing policy is preserve	rename in Domains, or set the policy to lower
keyword index count does not match the memories	the index drifted	Maintenance → Storage → Rebuild keyword index

Still stuck? memai-hook install --check and memai-admin --status report most of the state worth attaching to an issue.