Hippocortex OS — Beta Troubleshooting

Solutions to common issues encountered during beta usage.

Server Issues

Server won't start

Symptom: Container exits immediately or process crashes on launch.

Check 1: Port conflict

lsof -i :3100
# If something else is using 3100, either stop it or change the port:
# HIPPOCORTEX_PORT=3200 docker run ...

Check 2: Node.js version

node --version
# Must be v22.0.0 or higher

Check 3: Storage path permissions

# Docker
docker run --rm -v ~/hippocortex-data:/data alpine ls -la /data
# Ensure the directory exists and is writable

# Local
ls -la ./hippocortex.db
# Ensure the directory where the DB lives is writable

Check 4: Config validation error

docker logs hippocortex 2>&1 | head -20
# Look for "ConfigValidationError" — usually a bad env var value

Server starts but health check fails

Symptom: curl http://localhost:3100/api/v1/health returns connection refused or error.

Check 1: Is the server actually running?

docker ps | grep hippocortex
# If not listed, check: docker ps -a | grep hippocortex
# Then: docker logs hippocortex

Check 2: Is it binding to the right interface?

# If running in Docker, make sure you published the port:
docker run -p 3100:3100 ...
# Default bind is 0.0.0.0 — correct for Docker

Check 3: Firewall

# macOS
sudo pfctl -sr 2>/dev/null | grep 3100

# Linux
sudo iptables -L -n | grep 3100
sudo ufw status | grep 3100

Server becomes slow over time

Symptom: API responses that used to be fast now take seconds.

Check 1: Database size

ls -lh ~/hippocortex-data/hippocortex.db
# If > 5 GB, performance may degrade. Consider pruning old episodes.

Check 2: Memory usage

curl http://localhost:3100/api/v1/metrics | grep heap_used
# If heap > 1.5 GB, restart the server
docker restart hippocortex

Check 3: WAL file size

ls -lh ~/hippocortex-data/hippocortex.db-wal
# If WAL is > 100 MB, a checkpoint may be needed
# A clean restart triggers WAL checkpoint automatically
docker restart hippocortex

Authentication Issues

401 Unauthorized on every request

Cause 1: Wrong header name

# Correct:
curl -H "X-API-Key: hx_beta_yourkey" http://localhost:3100/api/v1/health/detailed

# Wrong:
curl -H "Authorization: Bearer hx_beta_yourkey" ...  # NOT supported

Cause 2: Key mismatch

# Check what keys the server expects:
docker exec hippocortex printenv HIPPOCORTEX_API_KEYS
# Compare with what your SDK is sending

Cause 3: Whitespace in key

# Check for trailing newline or spaces in your .env file
cat -A .env | grep API_KEYS
# '$' at end of line is normal. '^M$' (carriage return) is not.

429 Too Many Requests

Cause: Rate limit exceeded (default: 60 req/min).

# Check current rate limit setting
docker exec hippocortex printenv HIPPOCORTEX_RATE_LIMIT_RPM

# Increase if needed (requires restart):
# HIPPOCORTEX_RATE_LIMIT_RPM=120
docker restart hippocortex

Tip: If you're hitting rate limits during bulk import, batch your captures and add delays between calls.

SDK Issues

`ConnectionRefusedError` / `ECONNREFUSED`

Cause: SDK can't reach the server.

# Verify server is running and reachable
curl http://localhost:3100/api/v1/health

# Check SDK config
# baseUrl should match your server address exactly
# Common mistake: using https:// when server is http://

`synthesize()` returns empty results

Possible causes:

No events captured yet — call capture() first
learn() not called — memories aren't created until you trigger learning
Query doesn't match any memories — try broader search terms

# Verify data exists
curl -H "X-API-Key: hx_beta_yourkey" \
  http://localhost:3100/api/v1/health/detailed
# Check episodic count, semantic count

`learn()` is slow

Expected: learn() processes all unprocessed episodes. First call after many captures will be slow.

Mitigation:

Call learn() after each session instead of batching
Don't call more than once per minute
Run learn() in a background task, not in the request path

Data Issues

"Conflict detected" warnings

This is normal behavior. Hippocortex detected contradictory information and quarantined it. Examples:

"User's timezone is UTC" vs "User's timezone is EST"
"Deploy to staging first" vs "Deploy directly to prod"

The most recent information wins by default. You can inspect conflicts via the detailed health endpoint.

Database file is locked

Symptom: SQLITE_BUSY errors in logs.

Cause: Another process has the database open.

# Find what's using the file
fuser ~/hippocortex-data/hippocortex.db
# Or on macOS:
lsof ~/hippocortex-data/hippocortex.db

Fix: Ensure only one Hippocortex instance accesses the database at a time. Stop duplicate containers:

docker ps | grep hippocortex
# If multiple, stop extras:
docker stop hippocortex-duplicate

Restoring from backup

# 1. Stop the server
docker stop hippocortex

# 2. Replace the database
cp ~/hippocortex-data/backup-20260312.db ~/hippocortex-data/hippocortex.db

# 3. Remove WAL/SHM files (they belong to the old DB)
rm -f ~/hippocortex-data/hippocortex.db-wal
rm -f ~/hippocortex-data/hippocortex.db-shm

# 4. Start the server
docker start hippocortex

# 5. Verify
curl http://localhost:3100/api/v1/health

Docker Issues

Container keeps restarting

# Check exit code and logs
docker inspect hippocortex --format='{{.State.ExitCode}}'
docker logs --tail 50 hippocortex

Exit Code	Meaning	Fix
0	Clean exit	Check if restart policy is causing loops
1	Application error	Read logs for the error message
137	OOM killed	Increase container memory limit
143	SIGTERM (normal stop)	Normal, no fix needed

Volume mount issues

# Verify volume is mounted correctly
docker inspect hippocortex --format='{{json .Mounts}}' | jq

# Common mistake: mounting a file instead of a directory
# Wrong:  -v ~/hippocortex.db:/data/hippocortex.db
# Right:  -v ~/hippocortex-data:/data

Still Stuck?

Collect these before reaching out:
- Server logs: docker logs hippocortex 2>&1 | tail -100
- Health check: curl http://localhost:3100/api/v1/health/detailed
- Metrics: curl http://localhost:3100/api/v1/metrics
- OS and Docker version: uname -a && docker --version
- SDK version: npm list @hippocortex/sdk or pip show hippocortex
Email the beta support alias or post in the beta Discord/Slack channel with the above info.