Documentation

Error Handling & Debugging

Common Errors

Error	Cause	Fix
`Schema not finalized`	Writing data before `db.finalizeSchema()`	Call `CALL db.finalizeSchema()` after all type registrations
`Unknown node type`	Using a label not registered in the schema	Register the type with `db.registerNodeType()` before finalizing
`Unknown edge type`	Using a relationship type not registered	Register with `db.registerEdgeType()` before finalizing
`Node not found`	Creating an edge to a node that doesn't exist	Always `CREATE` the destination node before creating an edge to it
`Duplicate node type`	Registering the same type twice	Each type name must be unique — restart with a fresh volume if needed in dev
Connection refused on port 8080	Container not started or health check failing	Check `docker compose logs graphengine` for startup errors

Debugging with Logs

bash

# Follow live logs from the graph engine
docker compose logs -f graphengine

# Increase verbosity (set RUST_LOG=debug in docker-compose.yml)
# Valid values: error | warn | info | debug | trace

Testing Connectivity

bash

# Health endpoint
curl -v http://localhost:8080/health

# Verify Bolt port is open
nc -zv localhost 7687

# Simple Cypher round-trip
curl -sS -X POST http://localhost:8080/cypher \
  -H 'Content-Type: application/json' \
  -d '{"query":"RETURN 1 AS ping","parameters":{}}'
# → {"columns":["ping"],"rows":[[1]]}