mdcms/neuraldb-docs/pages/ops-troubleshooting.md

title	sort	section-id	keywords	description	language
Troubleshooting	140	operations	troubleshooting, errors, diagnostics, FAQ, common problems, debug	Common NeuralDB errors, diagnostic techniques, and frequently asked questions	en

Troubleshooting

Connection Issues

FATAL: password authentication failed

sudo -u neuraldb neuraldb-cli

ALTER USER neuraldb PASSWORD 'new-password';

could not connect to server: Connection refused

systemctl status neuraldb
ss -tlnp | grep 5432
journalctl -u neuraldb -n 50

Connection slots exhausted

SELECT count(*), state FROM pg_stat_activity GROUP BY state;
SELECT pg_terminate_backend(pid) FROM pg_stat_activity
WHERE state = 'idle' AND state_change < NOW() - INTERVAL '10 minutes';

Vector Query Issues

Slow Vector Searches

EXPLAIN (ANALYZE, BUFFERS)
SELECT id FROM documents ORDER BY embedding <=> '[...]' LIMIT 10;

Common causes: missing LIMIT, HNSW graph not in memory, ef_search too low.

SELECT * FROM neuraldb_stat_vector_indexes;  -- check hnsw_in_memory
SET enable_seqscan = off;  -- force index for debugging

Low Recall

SET hnsw.ef_search = 200;
SET neuraldb.vector_scan = 'exact';  -- compare against exact search

FAQ

Q: Can I use NeuralDB as a drop-in for PostgreSQL? Yes. NeuralDB implements the PostgreSQL wire protocol.

Q: What should vector_buffer be set to? SELECT SUM(hnsw_graph_size_bytes) FROM neuraldb_stat_vector_indexes — set vector_buffer at least this large.

Q: Is NeuralDB compatible with pgvector? Yes. All pgvector types (VECTOR, HALFVEC, SPARSEVEC) and operators (<=>, <->, <#>) work without modification.