Troubleshooting & Known Caveats
Relevant source files
The following files were used as context for generating this wiki page:
This page provides technical guidance on identifying, diagnosing, and resolving common issues within the AI-powered OpenMRS EHR system. It covers infrastructure initialization, frontend microfrontend loading, and AI service dependencies.
Infrastructure and Initialization Issues
The system relies on a multi-container Docker architecture. On initial startup, the OpenMRS backend undergoes significant database and module initialization which can lead to temporary service unavailability.
OpenMRS Backend Readiness
On a "cold start," the backend typically requires approximately 2 to 5 minutes to initialize its database and modules. During this period, the API will return HTTP 302 redirects to the /openmrs/initialsetup endpoint.
Sources: README.md:104-106, AGENTS.md:14-16, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:154-156
Metadata Initialization Failures
The metadata-init service is a one-shot container that creates 326 custom concepts, encounter types, and attributes. If this container exits with a non-zero code, it often indicates the OpenMRS backend was not ready or a network partition occurred.
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:214-220, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:417-425
The diagram above illustrates the sequential dependency of the metadata initialization process on the backend's readiness state.
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:52-70, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:214-225
AI Service and API Key Dependencies
The AI features (voice transcription, OCR, and LLM extraction) are dependent on external cloud providers (Sarvam AI and Google Gemini).
API Provider Errors
If AI endpoints return provider errors, verify the environment variables in the openMRS-main/.env file. The FastAPI backends will start without keys, but functional calls to AI endpoints will fail.
Sources: README.md:80-92, AGENTS.md:32-35, readmes/VOICE_VITALS_QUICK_START.md:59-70
Configuration Variables
| Variable | Purpose | Failure Symptom |
|---|---|---|
SARVAM_API_KEY | Voice transcription | Transcription times out or returns 401 |
GEMINI_API_KEY | OCR/Vitals Extraction | JSON extraction fails or returns null |
OPENMRS_API_URL | REST Connection | Connection refused / 404 in logs |
| Sources: README.md:84-92, readmes/VOICE_VITALS_QUICK_START.md:59-75 |
Frontend and Microfrontend Caveats
The frontend is a monorepo of microfrontends (ESMs) using Yarn Berry (4.10.3).
Missing Custom Tabs
If custom tabs (Intake, History, Assessment) are missing, ensure the dev server is started with yarn start:all. Using the standard yarn start only loads the base chart-app and omits the custom sidebar groups.
Sources: README.md:126-128, AGENTS.md:18-21
Broken Test Suites
The esm-patient-medical-documentation-app package contains a broken Jest configuration that references a missing openmrs/default-jest-config. Tests for this package will fail and should be excluded during CI runs.
Sources: README.md:173-177, AGENTS.md:28-30
The sequence diagram details a failure flow where missing browser permissions or invalid API keys interrupt the vital recording workflow.
Sources: readmes/VOICE_VITALS_QUICK_START.md:59-75, readmes/COMPLETION_CHECKLIST.md:154-165
Environment and Runtime Constraints
| Component | Constraint | Impact |
|---|---|---|
| Python Venv | Large dependencies (~2GB for Torch) | Slow setup; reuse existing venv |
| Docker Engine | Requires fuse-overlayfs & iptables-legacy | Stack fails to start in nested containers |
| Microphone | Requires HTTPS context | Recording button disabled in non-secure HTTP |
| RAM | 8GB Minimum recommended | Performance degradation or OOM crashes |
| Sources: AGENTS.md:24-35, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:105-115, readmes/VOICE_VITALS_QUICK_START.md:65-68 |
Emergency Procedures
In the event of critical failures, the following recovery steps are defined:
- Critical Bug in Production: Create a hotfix branch from
main, implement a minimal fix with a failing test case, and deploy immediately after verification. - Data Loss: Immediately stop all write operations, restore from the latest nightly MariaDB dump, and verify data integrity.
- Security Breach: Rotate all secrets (
SARVAM_API_KEY,GEMINI_API_KEY,MYSQL_ROOT_PASSWORD) and review access logs.
Sources: conductor/workflow.md:255-275, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:377-385
Conclusion
Most operational issues within the OpenMRS AI EHR system stem from cold-start initialization delays, missing cloud API credentials, or improper frontend launch commands. Following the healthcheck polling and environment verification steps outlined above ensures a stable deployment.