Connection Issues
Use this guide when clients can’t connect or connections fail intermittently.
Quick checks
Section titled “Quick checks”# Service healthcurl http://localhost:8080/readyz
# Channel statuscurl -s http://localhost:8080/observe/channels | jq
# Database connectivitycurl -s http://localhost:8080/observe/doctor | jq '.checks[] | select(.name | startswith("db"))'Symptom: LDAP Connection Refused
Section titled “Symptom: LDAP Connection Refused”Check 1: Is LDAP enabled?
Section titled “Check 1: Is LDAP enabled?”curl -s http://localhost:8080/observe/channels | jq '.ldap'Expected: enabled: true, running: true
If disabled: Set channels.ldap.enabled = true in config.
Check 2: Correct port?
Section titled “Check 2: Correct port?”curl -s http://localhost:8080/observe/channels | jq '.ldap.bindings[].actualPort'The actual port may differ from configured port if using ephemeral ports.
Check 3: Firewall
Section titled “Check 3: Firewall”Verify traffic is allowed to the LDAP port:
nc -zv identity-scribe-host 10389Symptom: REST API Returns 503
Section titled “Symptom: REST API Returns 503”Check 1: Is the service starting?
Section titled “Check 1: Is the service starting?”curl http://localhost:8080/startedzIf not started: Check logs for startup errors.
Check 2: Is the database connected?
Section titled “Check 2: Is the database connected?”curl -s http://localhost:8080/observe/doctor | jq '.checks.db'Check 3: Is initial sync complete?
Section titled “Check 3: Is initial sync complete?”curl http://localhost:8080/readyz?verboseReadiness requires initial sync to complete.
Symptom: Intermittent Timeouts
Section titled “Symptom: Intermittent Timeouts”Check 1: Connection pool exhaustion
Section titled “Check 1: Connection pool exhaustion”curl -s http://localhost:8080/metrics | grep -E "hikari.*(pending|active)"If pending > 0 frequently: Increase pool sizes.
Check 2: Source LDAP issues
Section titled “Check 2: Source LDAP issues”Check ingest lag:
curl -s http://localhost:8080/observe/stats/ingest | jq '.entry_types[].lag_seconds'High lag may indicate source LDAP connectivity issues.
Check 3: Network timeouts
Section titled “Check 3: Network timeouts”Increase timeouts if network is slow:
ldap.soTimeout = 30000database.queryHttpAcquisitionTimeout = 10sDatabase connection checklist
Section titled “Database connection checklist”| Check | Command |
|---|---|
| PostgreSQL running | pg_isready -h localhost -p 5432 |
| Credentials correct | Check SCRIBE_DATABASE_USER/PASSWORD |
| SSL required | Set ?sslmode=require in URL |
| Network reachable | nc -zv db-host 5432 |
| Pool not exhausted | Check hikaricp_connections_pending |
Related
Section titled “Related”- Deployment — System requirements
- Configuration — Connection settings
- Failures — Error codes