Troubleshooting

Symptom	Checks	Resolution
Setup script cannot reach localhost:8001	Confirm port 8001 is not published	Run it with docker compose exec kong bash -s < script.sh
Kong migration repeatedly restarts	Check kong-migration and kong-postgres logs	Verify database credentials match and Postgres is ready; do not repeatedly bootstrap an initialized database without review
Kong returns 401	Inspect route plugin and supplied header	Create the correct consumer/credential and use Basic Auth or apikey for the selected route
TLS validation fails	Inspect certificate SAN, expiry, and chain	Install a certificate for the node hostname and supply the trusted CA; do not normalize --insecure
HAPI is unavailable	Check HAPI and HAPI Postgres logs, disk, and env files	Correct database connectivity, then restart HAPI and query /fhir/metadata
Transformer cannot write FHIR	Check FHIR_SERVER_URL, Docker DNS, and HAPI metadata	Use the internal HAPI URL and verify the transformer mapping/configuration
Patient response is empty	Check identifier namespace and HAPI search result	Confirm a Patient identifier uses `https://healthtag.io
Hospital API returns 400	Check request fields and upstream validation	Supply both fields, verify HEALTHTAG_API_URL, and inspect sanitized API logs

Escalate safely

Preserve logs and versions, redact tokens/keys/patient data, and identify the exact failing step from verification. Known authorization defects must be handled as security incidents; see Security hardening.