Troubleshooting

Start here when something isn’t working.

curl http://localhost:8080/observe/doctor | jq

LDAP connection refused

• Verify LDAP channel enabled: curl http://localhost:8080/observe/channels
• Check port binding in startup banner

REST API returns 503

• Wait for startup: curl http://localhost:8080/startedz
• Check database: curl http://localhost:8080/observe/doctor

No colors in terminal

• Force: FORCE_COLOR=1 ./identity-scribe
• Disable: NO_COLOR=1 or FORCE_COLOR=0

Environment variables not applied

• Ensure variables use the SCRIBE_ prefix
• Check configuration priority order in Configuration

• Failures — Error codes, retries, and troubleshooting
• Monitoring — Operational workflows
• Observability — Metrics and traces

Include in support requests:

1. Error-Id from response header/body
2. Trace-Id if tracing enabled
3. Output of /observe/doctor