Troubleshooting Guide

Solutions to common issues and debugging techniques for NenDB deployments.

Common Issues

Connection Refused / Cannot Connect

Client cannot establish connection to NenDB server.

Possible Causes & Solutions:

Server Not Running

# Check if NenDB is running
ps aux | grep nendb

# Start NenDB service
systemctl start nendb

# Check service status
systemctl status nendb

Firewall Blocking Connection

# Allow port 3000 through firewall
sudo ufw allow 3000
sudo firewall-cmd --add-port=3000/tcp --permanent

# Check if port is open
netstat -tlnp | grep :3000
ss -tlnp | grep :3000

Incorrect Host/Port Configuration

# Check configuration
cat /etc/nendb/config.toml | grep -A 5 "\[server\]"

# Test connection
telnet localhost 3000
nc -zv localhost 3000

High Memory Usage / Out of Memory

NenDB consuming excessive memory or running out of available memory.

Solutions:

Check Memory Configuration

# Check current memory usage
free -h
ps -o pid,ppid,cmd,%mem,%cpu -p $(pgrep nendb)

# Review memory pool configuration
grep memory_pool_size /etc/nendb/config.toml

# Adjust memory pool size (restart required)
# Set to ~70% of available system memory
memory_pool_size = "4GB"

Enable Memory Monitoring

# Monitor memory usage over time
watch -n 5 'ps -o pid,ppid,cmd,%mem,%cpu -p $(pgrep nendb)'

# Check memory fragmentation
cat /proc/$(pgrep nendb)/status | grep -i mem

# Enable memory metrics
curl http://localhost:9090/metrics | grep nendb_memory

Slow Query Performance

Queries taking longer than expected to execute.

Performance Optimization:

Enable Query Profiling

# Enable detailed query logging
NENDB_LOG_LEVEL=debug

# Check slow query log
tail -f /var/log/nendb/nendb.log | grep "duration_ms"

# Profile specific query
EXPLAIN ANALYZE MATCH (n:User) WHERE n.age > 25 RETURN n

Optimize Batch Operations

# Increase batch size for bulk operations
batch_size = 50000

# Use async batch inserts for better throughput
client.batch_insert_async(data, batch_size=10000)

# Monitor batch performance
curl http://localhost:9090/metrics | grep nendb_batch

Data Corruption / Inconsistency

Data appears corrupted or queries return inconsistent results.

Recovery Steps:

Run Data Integrity Check

# Stop NenDB service first
systemctl stop nendb

# Run integrity check
nendb-cli --data-dir /var/lib/nendb/data --check-integrity

# Repair corrupted data
nendb-cli --data-dir /var/lib/nendb/data --repair

# Restart service
systemctl start nendb

Restore from Backup

# List available backups
ls -la /var/backups/nendb/

# Restore from backup (service must be stopped)
systemctl stop nendb
nendb-cli --restore /var/backups/nendb/backup-2024-01-15.tar.gz
systemctl start nendb

Debugging Techniques

Log Analysis

Enable Debug Logging

# Temporary debug mode
NENDB_LOG_LEVEL=debug systemctl restart nendb

# Or update config file
[logging]
level = "debug"
file = "/var/log/nendb/debug.log"

Common Log Patterns

# Connection issues
grep "connection" /var/log/nendb/nendb.log

# Memory warnings
grep -i "memory\|oom" /var/log/nendb/nendb.log

# Slow queries (>100ms)
grep "duration_ms.*[1-9][0-9][0-9]" /var/log/nendb/nendb.log

Performance Monitoring

Real-time Metrics

# CPU and memory usage
top -p $(pgrep nendb)

# I/O statistics
iotop -p $(pgrep nendb)

# Network connections
ss -tuln | grep :3000

Custom Metrics

# Query current metrics
curl -s http://localhost:9090/metrics

# Operations per second
curl -s http://localhost:9090/metrics | \
  grep nendb_operations_total

# Average response time
curl -s http://localhost:9090/metrics | \
  grep nendb_query_duration_avg

Client-Side Debugging

Connection Testing

# Test basic connectivity
telnet localhost 3000

# Test with client
import nendb
client = nendb.Client("tcp://localhost:3000", debug=True)
client.health_check()

Query Debugging

# Enable client-side logging
client = nendb.Client(
    "tcp://localhost:3000", 
    log_level="debug",
    log_queries=True
)

# Measure query performance
import time
start = time.time()
result = client.query("MATCH (n) RETURN n LIMIT 1000")
print(f"Query took: {time.time() - start:.3f}s")

Health Monitoring

Health Check Endpoints

# Basic health check
curl http://localhost:3000/health

# Detailed status
curl http://localhost:3000/status

# Readiness probe
curl http://localhost:3000/health/ready

Automated Monitoring

# Simple health check script
#!/bin/bash
response=$(curl -s -w "%{http_code}" http://localhost:3000/health)
if [[ "$response" != "200" ]]; then
  echo "NenDB health check failed: $response"
  # Send alert or restart service
fi

Getting Help

Community Support

GitHub Issues:Report bugs and request features
Discord Community:Join our Discord server
Stack Overflow:Use tagnendb

Enterprise Support

Email Support:support@nenco.co
Priority Support:24/7 support for enterprise customers
Professional Services:Custom consulting and training

Diagnostic Information

When reporting issues, please include the following diagnostic information:

# System Information
uname -a
lscpu | head -20
free -h
df -h

# NenDB Version and Configuration
nendb --version
cat /etc/nendb/config.toml

# Process Information
ps aux | grep nendb
systemctl status nendb

# Recent Logs (last 100 lines)
tail -100 /var/log/nendb/nendb.log

# Network Configuration
ss -tlnp | grep :3000
iptables -L -n | grep 3000

# Performance Metrics (if available)
curl -s http://localhost:9090/metrics | head -20

Was this page helpful?

Join the discussion Report an issue