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

# Troubleshooting

## Connection Issues

### `FATAL: password authentication failed`

```bash
sudo -u neuraldb neuraldb-cli
```
```sql
ALTER USER neuraldb PASSWORD 'new-password';
```

### `could not connect to server: Connection refused`

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

### Connection slots exhausted

```sql
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

```sql
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.

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

### Low Recall

```sql
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.