Troubleshooting Guide¶

Common issues and solutions for ORMDB.

Quick Diagnostics¶

# Check server status
ormdb admin status

# View recent logs
ormdb admin logs --tail 100

# Check connectivity
ormdb admin ping

# Verify data integrity
ormdb admin verify

Connection Issues¶

Cannot Connect to Server¶

Symptoms: - Connection refused - Connection timeout - "Server unavailable" error

Solutions:

Check if server is running

ormdb server status
# or
ps aux | grep ormdb

Verify port binding

netstat -tlnp | grep 8080
# or
ss -tlnp | grep 8080

Check firewall rules

# Linux
sudo iptables -L -n | grep 8080

# macOS
sudo pfctl -s rules | grep 8080

Verify configuration

ormdb config show | grep -E "host|port"

Connection Drops¶

Symptoms: - Intermittent disconnections - "Connection reset" errors

Solutions:

Check connection limits
```
ormdb admin stats | grep connections
```

Increase connection limit

# ormdb.toml
[server]
max_connections = 2000

Check for idle timeout

# ormdb.toml
[server]
idle_timeout_seconds = 300

Check client connection pooling

// Ensure proper pool configuration
let config = ClientConfig {
    max_connections: 20,
    idle_timeout: Duration::from_secs(300),
    ..Default::default()
};

Too Many Connections¶

Symptoms: - "Connection limit exceeded" error - New connections rejected

Solutions:

Check current connections
```
ormdb admin connections
```
Identify connection leaks
```
ormdb admin connections --by-client
```
Increase limit (if appropriate)
```
[server]
max_connections = 5000
```

Fix connection leaks in application

// Ensure connections are properly returned to pool
// Use connection pooling, not individual connections

Query Issues¶

Slow Queries¶

Symptoms: - Queries taking >1 second - Timeouts on large queries

Solutions:

Check slow query log
```
ormdb admin slow-queries --limit 10
```

Analyze query plan

ormdb query User "status = 'active'" --explain

Add missing indexes

ormdb schema add-index User user_status_idx status

Optimize includes

// Bad: Deep unbounded includes
.include(RelationInclude::new("posts")
    .include(RelationInclude::new("comments")))

// Good: Limited includes
.include(RelationInclude::new("posts")
    .with_limit(10)
    .with_fields(vec!["id", "title"]))

Use query budgets

.with_budget(FanoutBudget {
    max_entities: 1000,
    max_edges: 5000,
    max_depth: 3,
})

Query Budget Exceeded¶

Symptoms: - "Budget exceeded" error - Queries returning partial results

Solutions:

Add pagination

.with_pagination(Pagination::new(100, 0))

Reduce include depth

// Limit nesting
.include(RelationInclude::new("posts")
    .with_limit(10))  // Don't nest further

Increase budget (carefully)

[query]
max_entities = 20000
max_edges = 100000
max_depth = 6

Query Returns Wrong Results¶

Symptoms: - Missing expected data - Incorrect filter results

Solutions:

Verify filter syntax

// Check operator
FilterExpr::eq("status", Value::String("active".into()))
// Not
FilterExpr::eq("status", "active")  // Wrong type!

Check RLS policies
```
ormdb admin policies --entity User
```

Test without RLS

// Temporarily bypass RLS for debugging
let ctx = SecurityContext::admin();
client.query_with_context(query, ctx).await?;

Verify data exists

ormdb query User --filter "id = '...'" --context admin

Mutation Issues¶

Insert Fails¶

Symptoms: - "Constraint violation" error - Insert returns error

Solutions:

Check unique constraints
```
ormdb schema show User | grep unique
```

Verify required fields

// Ensure all non-nullable fields are provided
EntityData::new()
    .set("name", Value::String("Alice".into()))
    .set("email", Value::String("alice@example.com".into()))
    // Don't forget required fields!

Check foreign key references

# Verify referenced entity exists
ormdb query User --filter "id = 'referenced-id'"

Update Conflicts¶

Symptoms: - "Version conflict" error - Optimistic locking failures

Solutions:

Implement retry logic

loop {
    let entity = client.get("User", id).await?;
    let result = client.update("User", id,
        data.clone(),
        Some(entity.version)
    ).await;

    match result {
        Ok(_) => break,
        Err(Error::TransactionConflict { .. }) => {
            // Retry with fresh data
            continue;
        }
        Err(e) => return Err(e),
    }
}

Use transactions for complex updates

let tx = client.begin_transaction().await?;
// ... perform multiple operations
tx.commit().await?;

Delete Blocked¶

Symptoms: - "Restrict violation" error - Cannot delete entity

Solutions:

Check referencing entities
```
ormdb admin references User 'user-id'
```

Delete or reassign references first

// Delete child entities
client.delete_many("Post", FilterExpr::eq("author_id", user_id)).await?;
// Then delete parent
client.delete("User", user_id).await?;

Use cascade delete

let mutation = DeleteMutation::new("User")
    .with_id(user_id)
    .cascade();
client.mutate(Mutation::Delete(mutation)).await?;

Storage Issues¶

High Disk Usage¶

Symptoms: - Disk space warnings - Write failures

Solutions:

Check storage usage
```
ormdb admin stats --storage
```
Run compaction
```
ormdb admin compact
```
Trim WAL
```
ormdb admin wal trim --keep-days 7
```

Archive old data

# Export old data
ormdb query Event "created_at < '2023-01-01'" --format ndjson > old-events.ndjson

# Delete from database
ormdb delete Event "created_at < '2023-01-01'"

Low Cache Hit Rate¶

Symptoms: - Cache hit rate below 80% - Increased disk I/O

Solutions:

Check cache statistics
```
ormdb admin stats | grep cache
```

Increase cache size

[storage]
cache_size_mb = 1024  # Increase from 256

Analyze query patterns

# Look for queries scanning large amounts of data
ormdb admin slow-queries

Data Corruption¶

Symptoms: - Checksum errors - Inconsistent data - Server crashes

Solutions:

Run verification
```
ormdb admin verify
```
Repair if possible
```
ormdb admin repair
```

Restore from backup

ormdb server stop
ormdb backup restore latest.ormdb --target /var/lib/ormdb/data
ormdb server start

Performance Issues¶

High Memory Usage¶

Symptoms: - OOM kills - Swap usage - Slow performance

Solutions:

Check memory breakdown
```
ormdb admin stats --memory
```

Reduce cache size

[storage]
cache_size_mb = 256  # Reduce

Limit query results

[query]
max_entities = 5000  # Reduce default

Check for memory leaks

# Monitor over time
watch -n 60 'ormdb admin stats | grep memory'

High CPU Usage¶

Symptoms: - CPU constantly at 100% - Slow response times

Solutions:

Identify expensive queries
```
ormdb admin slow-queries
```

Add indexes

ormdb query User "email LIKE '%@example.com'" --explain
# If full scan, add index
ormdb schema add-index User user_email_idx email

Reduce parallelism
```
[query]
parallel_scan = false
```

Common Error Messages¶

"Entity not found"¶

// Entity doesn't exist
Err(Error::NotFound)

Cause: Querying non-existent entity ID.

Solution: Check ID validity, handle NotFound gracefully.

"Unique constraint violation"¶

Err(Error::ConstraintViolation(ConstraintError::UniqueViolation { .. }))

Cause: Duplicate value for unique field.

Solution: Use upsert or check existence first.

"Foreign key violation"¶

Err(Error::ConstraintViolation(ConstraintError::ForeignKeyViolation { .. }))

Cause: Referenced entity doesn't exist.

Solution: Create referenced entity first, or check reference validity.

"Schema mismatch"¶

Cause: Client schema doesn't match server.

Solution: Update client, run migrations, or sync schema.

"Budget exceeded"¶

Cause: Query would return too much data.

Solution: Add pagination, limits, or filters.

Getting Help¶

Collect Diagnostics¶

# Generate diagnostic report
ormdb admin diagnostics > diagnostics.txt

# Include:
# - Server version
# - Configuration (sanitized)
# - Recent errors
# - Statistics
# - Slow queries

Log Levels¶

# Enable debug logging temporarily
[logging]
level = "debug"

Support Channels¶

GitHub Issues: Bug reports and feature requests
Discussions: Questions and community help
Documentation: API reference and guides

Next Steps¶

Error Reference - Complete error documentation
CLI Reference - All admin commands
Monitoring - Set up proactive alerts