Baradb/docs/de/troubleshooting.md

Fehlerbehebungsleitfaden

Installationsprobleme

Nim nicht gefunden

im: command not found

Lösung:

# Linux/macOS
curl https://nim-lang.org/choosenim/init.sh -sSf | sh

# Zu PATH hinzufügen
echo 'export PATH=$HOME/.nimble/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

SSL-Kompilierungsfehler

Error: BaraDB requires SSL support. Compile with -d:ssl

Lösung: Immer mit -d:ssl kompilieren:

nim c -d:ssl -d:release -o:build/baradadb src/baradadb.nim

Fehlende Abhängigkeiten

Error: cannot open file: hunos

Lösung:

nimble install -d -y

Laufzeitprobleme

Port bereits in Verwendung

Error: unhandled exception: Address already in use [OSError]

Lösung 1: Port ändern:

BARADB_PORT=5433 ./build/baradadb

Lösung 2: Bestehenden Prozess beenden:

lsof -ti:9472 | xargs kill -9
# oder
fuser -k 9472/tcp

Permission Denied auf Datenverzeichnis

Error: cannot create directory: Permission denied

Lösung:

mkdir -p ./data
chmod 755 ./data
# Oder anderes Verzeichnis verwenden
BARADB_DATA_DIR=/tmp/baradb_data ./build/baradadb

Out of Memory

Error: out of memory

Lösung: Speicherverbrauch reduzieren:

BARADB_MEMTABLE_SIZE_MB=32 \
BARADB_CACHE_SIZE_MB=128 \
BARADB_VECTOR_EF_CONSTRUCTION=100 \
./build/baradadb

Disk Full

Error: No space left on device

Lösung:

# Disk-Nutzung prüfen
df -h

# Compaction auslösen um Platz freizugeben
curl -X POST http://localhost:9470/api/admin/compact

# Oder manuell
./build/baradadb --compact

Abfrageprobleme

Syntaxfehler

Error: Syntax error at position 15: unexpected token

Lösung: Abfragesyntax prüfen:

-- Korrekt
SELECT name, age FROM users WHERE age > 18;

-- Inkorrekt (fehlendes Komma)
SELECT name age FROM users WHERE age > 18;

Tabelle nicht gefunden

Error: Table 'users' does not exist

Lösung: Zuerst Schema erstellen:

CREATE TYPE User {
  name: str,
  age: int32
};

Typ-Mismatch

Error: Cannot compare int32 with str

Lösung: Korrekte Typen verwenden:

-- Korrekt
SELECT * FROM users WHERE age > 18;

-- Inkorrekt
SELECT * FROM users WHERE age > '18';

Timeout

Error: Query execution timeout

Lösung: LIMIT hinzufügen oder optimieren:

-- Limit hinzufügen
SELECT * FROM large_table LIMIT 1000;

-- Index verwenden
SELECT * FROM users WHERE id = 123;

Verbindungsprobleme

Connection Refused

Connection refused: localhost:9472

Lösung:

# Prüfen ob Server läuft
ps aux | grep baradadb

# Server starten
./build/baradadb

# Firewall prüfen
sudo ufw status
sudo ufw allow 9472

Authentifizierung fehlgeschlagen

Error: Authentication failed

Lösung:

# Prüfen ob JWT-Geheimnis übereinstimmt
BARADB_AUTH_ENABLED=true \
BARADB_JWT_SECRET="correct-secret" \
./build/baradadb

Performance-Probleme

Langsame Abfragen

Diagnose:

# Abfrageplan prüfen
curl -X POST http://localhost:9470/api/explain \
  -d '{"query": "SELECT * FROM large_table"}'

Lösungen:

1. Indizes hinzufügen:

CREATE INDEX idx_users_name ON users(name);

2. LIMIT verwenden:

SELECT * FROM users LIMIT 100;

3. Cache erhöhen:

BARADB_CACHE_SIZE_MB=1024 ./build/baradadb

Hohe CPU-Nutzung

Ursachen:

• Compaction läuft
• Große Vektor-Suche ohne HNSW
• Komplexe Graph-Traversierung

Lösungen:

# Compaction-Intervall anpassen
BARADB_COMPACTION_INTERVAL_MS=300000 ./build/baradadb

# Approximative Vektor-Suche verwenden
SELECT /*+ APPROXIMATE */ * FROM vectors
ORDER BY cosine_distance(embedding, [...])
LIMIT 10;

Cluster-Probleme

Raft Split-Brain

Warning: Multiple leaders detected

Lösung: Ungerade Anzahl von Knoten sicherstellen (3, 5, 7). Minority-Partition neu starten.

Replikations-Lag

Warning: Replication lag > 10s

Lösung:

# Netzwerk-Latenz prüfen
ping replica-node

# Replikations-Threads erhöhen
BARADB_REPLICATION_THREADS=4 ./build/baradadb

# Auf Async-Replikation umschalten
BARADB_REPLICATION_MODE=async

Datenkorruption

Prüfsummen-Mismatch

Error: SSTable checksum mismatch

Lösung:

# Korrupte SSTable entfernen (Daten werden aus WAL wiederhergestellt)
rm ./data/sstables/corrupted.sst

# Neustarten und wiederherstellen
./build/baradadb --recover

Debug-Modus

Debug-Logging für detaillierte Diagnostik aktivieren:

BARADB_LOG_LEVEL=debug \
BARADB_LOG_FILE=/tmp/baradb_debug.log \
./build/baradadb

Hilfe erhalten

Wenn das Problem weiterhin besteht:

1. Logs prüfen: tail -f /var/log/baradb/baradb.log
2. Metrics prüfen: curl http://localhost:9470/metrics
3. Diagnostik ausführen: ./build/baradadb --diagnose
4. Issue öffnen mit:
   • BaraDB Version (./build/baradadb --version)
   • OS und Architektur
   • Relevante Log-Auszüge
   • Schritte zur Reproduktion