Skip to content
IdentityScribe

Connection Issues

Clients can’t connect, or connections drop intermittently. Work through the checks below to isolate the problem.

Connection path

Where failures happen

Client
Connection refused Port, firewall
Network / Firewall
503 Service Unavailable Starting up, not ready
IdentityScribe
Intermittent timeouts Pool exhaustion, backend down
LDAP Backend
Database errors Auth, connectivity, SSL
PostgreSQL
Match your error to the right section below for diagnosis steps

Quick checks

Section titled “Quick checks”
Terminal window
# Service health
curl http://localhost:8080/readyz


# Channel status
curl -s http://localhost:8080/observe/channels | jq


# Database connectivity
curl -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?”
Terminal window
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?”
Terminal window
curl -s http://localhost:8080/observe/channels | jq '.ldap.bindings[].actualPort'

The actual port may differ from the configured port when using ephemeral ports.

Check 3: Firewall

Section titled “Check 3: Firewall”

Verify traffic is allowed to the LDAP port:

Terminal window
nc -zv identity-scribe-host 10389

Symptom: 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?”
Terminal window
curl http://localhost:8080/startedz

If not started: Check logs for startup errors.

Check 2: Is the database connected?

Section titled “Check 2: Is the database connected?”
Terminal window
curl -s http://localhost:8080/observe/doctor | jq '.checks.db'

Check 3: Is initial sync complete?

Section titled “Check 3: Is initial sync complete?”
Terminal window
curl http://localhost:8080/readyz?verbose

Readiness requires initial sync to complete.

Symptom: Intermittent timeouts

Section titled “Symptom: Intermittent timeouts”

Check 1: Pool exhaustion

Section titled “Check 1: Pool exhaustion”
Terminal window
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:

Terminal window
curl -s http://localhost:8080/observe/stats/ingest | jq '.entry_types[].lag_seconds'

High lag points to source LDAP problems.

Check 3: Network timeouts

Section titled “Check 3: Network timeouts”

Increase timeouts if the network is slow:

ldap.soTimeout = 30000
database.queryHttpAcquisitionTimeout = 10s

Database connection checklist

Section titled “Database connection checklist”
CheckCommand
PostgreSQL runningpg_isready -h localhost -p 5432
Credentials correctCheck SCRIBE_DATABASE_USER/PASSWORD
SSL requiredSet ?sslmode=require in URL
Network reachablenc -zv db-host 5432
Pool not exhaustedCheck hikaricp_connections_pending
Section titled “Related”