Troubleshooting Guide

Common Issues (50+)

Most frequent issues and step-by-step solutions. Common Issues

Performance Issues

Slow queries, high latency, connection pool exhaustion, database bottlenecks. Performance Issues

Security Issues

Authorization, authentication, JWT, RLS, data exposure. Security Issues

Federation & NATS

Federation timeouts, saga failures, NATS connectivity. Federation & NATS

Transport issues

gRPC

“gRPC connection fails immediately” — gRPC requires HTTP/2. Check that your load balancer or reverse proxy is configured for HTTP/2 pass-through or gRPC backend protocol. See the Kubernetes gRPC guide, AWS ALB guide, or nginx gRPC config.

“Received HTTP/1.1 response on gRPC connection” — A proxy or load balancer is downgrading HTTP/2 to HTTP/1.1. Configure the load balancer to use the GRPC or HTTP2 backend protocol.

“gRPC server streaming stops after first message” — Check that the proxy does not have request or response buffering enabled. gRPC streaming requires unbuffered HTTP/2 frames.

REST

“REST endpoint returns 404” — REST routes follow the pattern /rest/v1/<resource> (configurable via [rest] path). Verify the resource name matches your schema and that fraiseql run started without compile errors.

“REST POST body not accepted” — REST mutations expect Content-Type: application/json.

Diagnostic commands

# Health check
curl http://localhost:8080/health

# Debug logging
RUST_LOG=debug fraiseql run

# Database connectivity
psql "$DATABASE_URL" -c "SELECT 1"

# Active connections (PostgreSQL)
psql "$DATABASE_URL" -c "SELECT usename, count(*) FROM pg_stat_activity GROUP BY usename"

Getting help

1. Check logs first — RUST_LOG=debug fraiseql run reveals most issues
2. Search GitHub Issues — your problem may already have a solution
3. Ask on Discord — include your FraiseQL version (fraiseql --version), error message, and a minimal reproduction