Troubleshooting

`recollectium` command not found

Open a new shell after installation. If recollectium is still not found, check the directory where uv installs tool executables:

uv tool dir --bin
uv tool list

Add the reported bin directory to PATH, then restart your shell. Common defaults are:

# Linux and macOS
export PATH="$HOME/.local/bin:$PATH"

# Windows PowerShell
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"

Then verify the installed command directly:

recollectium --version
recollectium --help

After a bootstrap install, you should run recollectium directly. You should not need to prefix normal commands with uv.

If uv itself is also not found after bootstrap install, check its platform-specific install location. On Linux and macOS, uv is commonly under $HOME/.local/bin. On Windows bootstrap installs uv at %LOCALAPPDATA%\uv\uv.exe, while the Recollectium tool executable is under %USERPROFILE%\.local\bin. Add the missing directory to PATH, then open a new shell.

If installed from a source checkout rather than through bootstrap, use the development form from the repository root:

uv run recollectium --help

First init is slow

The first recollectium init downloads the local FastEmbed model cache. This can take 30 to 120 seconds.

Retry if the network failed:

recollectium init

Config validation fails

Run:

recollectium config doctor
recollectium config --validate
recollectium config --path

If needed, reset to defaults:

recollectium config reset

Database migration failed

If startup or an upgrade fails while applying a migration, stop the service and check the logs. The failed migration step rolls back, so the database stays on the last successful version.

After you fix the underlying problem, rerun the same command. If the failure happened during a service start, start the service again. If it happened during upgrade, run the same upgrade command again.

Database is newer than this install

Recollectium does not support downgrading to an older build after a newer schema has been written. If the database is newer than the installed version, upgrade Recollectium to a build that understands that schema or restore a backup from before the newer upgrade.

Back up or restore the database

There is no dedicated backup command in v1. For a manual backup, stop the service first, then copy the Recollectium data directory or the SQLite database file to a safe location.

To recover from corruption, stop Recollectium, restore that copy, then start the service again. If you restore an older backup, Recollectium will migrate it forward automatically when it opens the database.

Service will not start

Check status and logs:

recollectium service status
recollectium service discover
recollectium webui status

Look in the logs directory. See Logs.

A stale PID file is usually cleaned automatically by status or discovery commands.

Port already in use

Change the service port:

recollectium config set service.port 9090
recollectium service restart --type api

If the WebUI port is busy, change the WebUI port instead:

recollectium config set webui.port 8767
recollectium webui restart

Search returns unexpected results

Try these checks:

Search the correct scope: user vs workspace.
Confirm the workspace UID.
Search without --type first.
Include archived memories if needed.
Check embedding status.

recollectium workspace resolve my-project
recollectium embedding-status
recollectium embedding-jobs

MCP client cannot connect

For stdio clients, verify the configured command works in a shell:

recollectium mcp-stdio

For managed MCP service mode:

recollectium service start mcp
recollectium service status

API client cannot connect

Start the API service and validate health:

recollectium service start api
curl http://127.0.0.1:8765/v1/health

WebUI cannot connect

Start the WebUI and confirm its status:

recollectium webui start
recollectium webui status

Unsafe host binding warning

If you changed service.host or the WebUI host to 0.0.0.0, a LAN IP, or a VPN IP, remember that v1 services are unauthenticated. Use private networking and external access controls.