Troubleshooting Guide

# Check your Zig version
zig version

# Geode requires Zig 0.1.0+
# Install correct version if needed
# On Linux (from ziglang.org):
wget https://ziglang.org/download/0.1.0/zig-linux-x86_64-0.1.0.tar.xz
tar xf zig-linux-x86_64-0.1.0.tar.xz
export PATH="$(pwd)/zig-linux-x86_64-0.1.0:$PATH"

# Verify version
zig version  # Should show 0.1.0

# Rebuild
cd geode
make clean
make build

sudo apt-get update
sudo apt-get install -y \
    build-essential \
    libssl-dev \
    pkg-config \
    git \
    curl

brew install openssl pkg-config

# For debug build (requires less memory):
make build

# For release build (requires ~4GB RAM):
# Add swap if needed
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Then build
make release

# Check what's using port 3141
lsof -i :3141

# Or use netstat
netstat -tulpn | grep 3141

# Kill the process if it's a stuck Geode instance
kill -9 <PID>

# Option 1: Use a different port
geode serve --listen 0.0.0.0:8443

# Option 2: Stop the conflicting process
# If it's an old Geode server:
pkill geode

# Then start server
geode serve --listen 0.0.0.0:3141

# Check data directory permissions
ls -la /var/geode/data

# Check ownership
stat /var/geode/data

# Option 1: Fix permissions
sudo chown -R $USER:$USER /var/geode/data
chmod -R 755 /var/geode/data

# Option 2: Use a directory you own
mkdir -p ~/geode-data
geode serve \
    --listen 0.0.0.0:3141 \
    --data-dir ~/geode-data

# Check if certificate files exist
ls -la server.crt server.key

# Verify certificate is valid
openssl x509 -in server.crt -text -noout

# Check certificate and key match
openssl x509 -noout -modulus -in server.crt | openssl md5
openssl rsa -noout -modulus -in server.key | openssl md5
# These should match

# Generate self-signed certificate for development
openssl req -x509 -newkey rsa:4096 \
    -keyout server.key \
    -out server.crt \
    -days 365 \
    -nodes \
    -subj "/CN=localhost"

# Start server with certificate
geode serve \
    --listen 0.0.0.0:3141 \
    --tls-cert server.crt \
    --tls-key server.key

# Install certbot
sudo apt-get install certbot

# Get certificate (requires domain)
sudo certbot certonly --standalone -d yourdomain.com

# Certificates will be in:
# /etc/letsencrypt/live/yourdomain.com/fullchain.pem
# /etc/letsencrypt/live/yourdomain.com/privkey.pem

# Start server
sudo geode serve \
    --listen 0.0.0.0:3141 \
    --tls-cert /etc/letsencrypt/live/yourdomain.com/fullchain.pem \
    --tls-key /etc/letsencrypt/live/yourdomain.com/privkey.pem

# Run with debug logging
geode serve \
    --listen 0.0.0.0:3141 \
    --log-level debug

# Check system logs
journalctl -xe | grep geode

# Check for core dumps
coredumpctl list geode
coredumpctl info <ID>

# Verify server is running
ps aux | grep geode

# Check if port is listening
netstat -tulpn | grep 3141

# Test connectivity
telnet localhost 3141

# Check firewall
sudo iptables -L | grep 3141

# If server isn't running, start it
geode serve --listen 0.0.0.0:3141

# If firewall is blocking, open port
sudo ufw allow 3141/tcp
sudo ufw allow 3141/udp  # QUIC uses UDP

# For remote connections, ensure server binds to 0.0.0.0
# NOT 127.0.0.1 (localhost only)
geode serve --listen 0.0.0.0:3141

# Python client - disable verification (dev only!)
from geode_client import Client
client = Client(host="localhost", port=3141, skip_verify=True)

# Go client - disable verification (dev only!)
db, err := sql.Open("geode", "localhost:3141?insecure_tls_skip_verify=true")

# Rust client - disable verification (dev only!)
use geode_client::Client;
let client = Client::new("localhost", 3141).skip_verify(true);
let mut conn = client.connect().await?;

# Provide CA certificate path
# Python
from geode_client import Client
client = Client(host="localhost", port=3141, ca_cert="/path/to/ca.crt")

# Go
db, err := sql.Open("geode", "localhost:3141?ca=/path/to/ca.crt")

# Rust
use geode_client::Client;
let client = Client::new("localhost", 3141).skip_verify(false);
let mut conn = client.connect().await?;

# Check if QUIC port (UDP) is accessible
nc -zu <server-ip> 3141

# Check server logs for QUIC errors
geode serve --log-level debug 2>&1 | grep QUIC

# Verify UDP is not blocked by firewall
sudo tcpdump -i any udp port 3141

# Validate UDP connectivity and QUIC MTU settings

# Check MTU issues (QUIC requires proper MTU)
ping -M do -s 1400 <server-ip>

# If MTU is too low, configure on server/network

# Increase max connections on server
geode serve \
    --listen 0.0.0.0:3141 \
    --max-connections 10000

# Increase pool size on client
# Go
db.SetMaxOpenConns(100)
db.SetMaxIdleConns(10)
db.SetConnMaxLifetime(time.Hour)

# Python
from geode_client import ConnectionPool
pool = ConnectionPool(host="localhost", port=3141, max_size=100, timeout=30.0)

# Rust
use geode_client::ConnectionPool;
let pool = ConnectionPool::new("localhost", 3141, 100);

-- WRONG: Using reserved keyword without backticks
MATCH (return:Person) RETURN return.name

-- CORRECT: Use backticks for reserved words
MATCH (`return`:Person) RETURN `return`.name

-- WRONG
MATCH (n:Social Network) RETURN n

-- CORRECT
MATCH (n:`Social Network`) RETURN n

-- WRONG: Missing $ for parameters
MATCH (n:Person {name: name_param}) RETURN n

-- CORRECT: Use $ prefix
MATCH (n:Person {name: $name_param}) RETURN n

# Use EXPLAIN to see where parser fails
geode query "EXPLAIN <your query here>"

-- First, check what labels exist
MATCH (n) RETURN DISTINCT labels(n) AS existing_labels;

-- Create missing labels/nodes
CREATE (p:Person {name: "Alice", age: 30});

-- Use MERGE if unsure if node exists
MERGE (p:Person {id: 1})
ON CREATE SET p.name = "Alice"
ON MATCH SET p.lastSeen = timestamp();

-- WRONG: Comparing string to number
MATCH (p:Person) WHERE p.age = "30" RETURN p

-- CORRECT: Use consistent types
MATCH (p:Person) WHERE p.age = 30 RETURN p

-- WRONG
RETURN "hello" + 5

-- CORRECT: Convert first
RETURN toInt("123") + 5

-- NULL comparisons require IS NULL / IS NOT NULL
MATCH (p:Person) WHERE p.age IS NOT NULL RETURN p

-- Arithmetic with NULL returns NULL
RETURN 5 + null  -- Returns null

-- WARNING: Cartesian product (every person × every book)
MATCH (p:Person)
MATCH (b:Book)
RETURN p.name, b.title
-- If 1000 people and 1000 books = 1,000,000 rows!

-- Connect the patterns
MATCH (p:Person)-[:READ]->(b:Book)
RETURN p.name, b.title

-- Or use WHERE to filter
MATCH (p:Person), (b:Book)
WHERE p.favoriteGenre = b.genre
RETURN p.name, b.title

# Use PROFILE to see execution metrics
geode query "PROFILE MATCH (n:Person) RETURN n"

# Use EXPLAIN to see query plan
geode query "EXPLAIN MATCH (n:Person WHERE n.age > 30) RETURN n"

# Look for:
# - "Scan" without index (bad for large datasets)
# - Large "EstimatedRows" counts
# - Missing index usage

-- Create index on frequently queried properties
CREATE INDEX person_age ON Person(age);
CREATE INDEX person_name ON Person(name);

-- For full-text search
CREATE FULLTEXT INDEX person_bio ON Person(bio);

-- For spatial queries
CREATE SPATIAL INDEX location_coords ON Location(coordinates);

-- For vector similarity
CREATE VECTOR INDEX doc_embedding ON Document(embedding);

-- Verify indexes exist
SHOW INDEXES;

-- SLOW: Filtering after collecting all data
MATCH (p:Person)
WHERE p.age > 30
RETURN p

-- FASTER: Use index-backed property filter in MATCH
MATCH (p:Person {age: 30})  -- Exact match uses index
RETURN p

-- For ranges, ensure index exists first
CREATE INDEX person_age ON Person(age);
-- Then query
MATCH (p:Person) WHERE p.age > 30 RETURN p

# Monitor server memory
ps aux | grep geode

# Check page cache size
geode serve --page-cache-size 512  # MB

# Monitor with metrics
curl http://localhost:9090/metrics | grep memory

# Default is 1024MB, reduce if needed
geode serve \
    --listen 0.0.0.0:3141 \
    --page-cache-size 256

-- Always use LIMIT for large result sets
MATCH (n) RETURN n LIMIT 1000

-- Use pagination
MATCH (n:Person)
RETURN n
ORDER BY n.id
SKIP 1000
LIMIT 100

# Python - stream results instead of loading all
for row in client.rows.query_stream("MATCH (n:Person) RETURN n"):
    process(row)  # Process one row at a time

# Check if index exists
geode query "SHOW INDEXES"

# Use EXPLAIN to see if index is used
geode query "
  EXPLAIN MATCH (p:Person WHERE p.email = '[email protected]')
  RETURN p
"

# Look for "IndexSeek" or "IndexScan" in plan
# If you see "NodeScan", index is NOT being used

-- Create it
CREATE INDEX person_email ON Person(email);

-- Index on "name" won't help this query:
MATCH (p:Person) WHERE p.email = '...' RETURN p

-- Need index on "email":
CREATE INDEX person_email ON Person(email);

-- WRONG: Function prevents index usage
MATCH (p:Person) WHERE toLower(p.name) = 'alice' RETURN p

-- BETTER: Store normalized value
MATCH (p:Person) WHERE p.normalizedName = 'alice' RETURN p

-- Or create expression index (if supported):
CREATE INDEX person_name_lower ON Person(toLower(name));

-- SLOW: Count all nodes of a label
MATCH (p:Person) RETURN count(p)

-- FASTER: If you maintain counts in a separate node
MATCH (stats:Statistics {label: 'Person'}) RETURN stats.count

-- Update count when adding/removing
MATCH (stats:Statistics {label: 'Person'})
SET stats.count = stats.count + 1

-- Use materialized views (if available)
CREATE MATERIALIZED VIEW person_stats AS
  MATCH (p:Person)
  RETURN count(p) AS total,
         avg(p.age) AS avg_age,
         min(p.age) AS min_age,
         max(p.age) AS max_age
REFRESH COMPLETE;

-- Query the view
SELECT * FROM person_stats;

import time
import random
from geode_client import Client, QueryError

client = Client(host="localhost", port=3141)

async def execute_with_retry(conn, query, max_retries=3):
    for attempt in range(max_retries):
        try:
            await conn.query(query)
            return
        except QueryError:
            if attempt == max_retries - 1:
                raise
            # Exponential backoff with jitter
            wait = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait)

# async with client.connection() as conn:
#     await execute_with_retry(conn, "MATCH (n) RETURN count(n)")

-- BAD: Inconsistent ordering across transactions
-- Transaction 1: Locks Alice, then Bob
-- Transaction 2: Locks Bob, then Alice
-- = DEADLOCK RISK

-- GOOD: Always lock in same order (e.g., by ID)
BEGIN TRANSACTION;
  MATCH (a:Person {id: 1})
  MATCH (b:Person {id: 2})
  SET a.balance = a.balance - 100,
      b.balance = b.balance + 100;
COMMIT;

# Server-side timeout configuration
geode serve \
    --listen 0.0.0.0:3141 \
    --transaction-timeout 300  # seconds

# SLOW: One huge transaction
async with client.connection() as tx:
    await tx.begin()
    for i in range(100000):
        await tx.execute("CREATE (n:Node {id: $id})", {"id": i})
    await tx.commit()

# FASTER: Batch into smaller transactions
batch_size = 1000
for i in range(0, 100000, batch_size):
    async with client.connection() as tx:
        await tx.begin()
        for j in range(i, min(i + batch_size, 100000)):
            await tx.execute("CREATE (n:Node {id: $id})", {"id": j})
        await tx.commit()

BEGIN TRANSACTION;
  CREATE (a:Person {name: "Alice"});
  SAVEPOINT sp1;
  CREATE (b:Person {name: "Bob"});
  ROLLBACK TO sp1;  -- Bob creation rolled back
  -- Alice is still there
  COMMIT;  -- Alice persists, Bob does not

BEGIN TRANSACTION;
  SAVEPOINT sp1;
  CREATE (a:Person {name: "Alice"});
  CREATE (b:Person {name: "Bob"});
  ROLLBACK TO sp1;  -- Both Alice and Bob rolled back
  CREATE (c:Person {name: "Charlie"});
COMMIT;  -- Only Charlie persists

import asyncio

# WRONG: Reusing closed loop
loop = asyncio.get_event_loop()
loop.run_until_complete(main())
loop.close()
loop.run_until_complete(another_func())  # ERROR

# CORRECT: Use asyncio.run()
asyncio.run(main())
asyncio.run(another_func())

# Or manage loop properly
loop = asyncio.new_event_loop()
asyncio.set_event_loop(loop)
try:
    loop.run_until_complete(main())
finally:
    loop.close()

import (
    "database/sql"
    "time"
)

db, err := sql.Open("geode", "localhost:3141")
if err != nil {
    log.Fatal(err)
}

// Configure pool
db.SetMaxOpenConns(25)              // Max open connections
db.SetMaxIdleConns(5)               // Idle connections in pool
db.SetConnMaxLifetime(5 * time.Minute)  // Max lifetime
db.SetConnMaxIdleTime(1 * time.Minute)  // Max idle time

// Always use context with timeout
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

rows, err := db.QueryContext(ctx, "MATCH (n) RETURN n LIMIT 10")

use geode_client::{Client, Error};

let client = Client::new("localhost", 3141).skip_verify(false);
let mut conn = client.connect().await?;

let mut retries = 3;
while retries > 0 {
    match conn.query("MATCH (n) RETURN n LIMIT 10").await {
        Ok(_) => break,
        Err(Error::Connection(_)) if retries > 1 => {
            retries -= 1;
            tokio::time::sleep(std::time::Duration::from_secs(1)).await;
        }
        Err(e) => return Err(e),
    }
}

const std = @import("std");
const geode = @import("geode_client");

pub fn main() !void {
    // Use larger allocator for large result sets
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    var client = try geode.Client.init(allocator, .{
        .host = "localhost",
        .port = 3141,
    });
    defer client.deinit();

    // For very large results, use streaming or pagination
    const result = try client.query(
        "MATCH (n) RETURN n LIMIT 1000"  // Limit result size
    );
    defer result.deinit();

    // Process results in batches
    while (try result.next()) |row| {
        // Process row
        // Memory is freed after each iteration
    }
}

# Check if server is responsive
curl http://localhost:9090/health

# Check readiness (for K8s)
curl http://localhost:9090/ready

# View metrics
curl http://localhost:9090/metrics

# View recent errors
journalctl -u geode -n 100 | grep ERROR

# Follow logs in real-time
journalctl -u geode -f

# Filter by severity
geode serve --log-level debug 2>&1 | grep -E 'ERROR|WARN'

# Search for specific error
grep "GQLSTATUS 42000" /var/log/geode/server.log

# Test QUIC connectivity (requires netcat with QUIC support)
nc -zu <server-ip> 3141

# Test with client
geode query "RETURN 1"

# Verbose connection debug
export GEODE_LOG_LEVEL=debug
geode query "RETURN 1"

-- Profile a slow query
PROFILE
MATCH (p:Person)-[:KNOWS*1..3]->(f:Person)
WHERE p.name = 'Alice'
RETURN f.name, count(*) AS connections
ORDER BY connections DESC
LIMIT 10;

-- Explain query plan
EXPLAIN
MATCH (p:Person {age: 30})
RETURN p;

-- Check current queries (if monitoring enabled)
CALL db.currentQueries();

-- Show active transactions
CALL db.transactions();

**Geode Version**: v0.1.3
**OS**: Ubuntu 22.04 LTS
**Zig Version**: 0.1.0

**Issue**: Query with CASE expression fails with syntax error

**Query**:
```gql
MATCH (p:Person)
RETURN p.name, CASE WHEN p.age < 30 THEN 'young' ELSE 'senior' END AS category

GQLSTATUS 42000: Syntax error near 'CASE'

[ERROR] Parser failed at line 2, column 20

---

## Next Steps

- [Configuration Reference](/docs/configuration/server-configuration/) - Tune server settings
- [Query Performance](/docs/query/performance-tuning/) - Optimize slow queries
- [Security Guide](/docs/security/overview/) - Harden production deployment
- [Deployment Guide](/docs/ops/deployment/) - Production deployment patterns
- [Monitoring](/docs/ops/observability/) - Set up metrics and alerts