Solving Common Problems When Building Reports
This guide helps you diagnose and resolve common issues when building reports in the OpenMRS Reporting Module.
When building reports in OpenMRS, you may encounter issues with cohort queries not finding patients, indicators showing unexpected results, parameters not working correctly, or reports running too slowly. This troubleshooting guide provides step-by-step solutions for the most common problems, organized by component type to help you quickly identify and fix issues. Start by matching your symptoms to the relevant section below, then work through the suggested checks and solutions systematically.
Table of Contents
Common Issues and Solutions
🚫 Cohort Query Problems
Issue: "No patients found"
Check: Date ranges are realistic
Check: Location parameter is correct
Check: Cohort criteria aren't too restrictive
Solution: Test with broader criteria first
Issue: "Too many patients returned"
Check: Missing date restrictions
Check: Location filter not applied
Solution: Add more specific criteria
Issue: "Query timeout"
Check: Date range too large
Check: Complex SQL without indexes
Solution: Optimize query or break into smaller pieces
📊 Indicator Calculation Issues
Issue: "Unexpected percentage results"
Check: Numerator/denominator cohort definitions
Check: Parameter mapping between indicator and cohorts
Solution: Test numerator and denominator separately
Issue: "Division by zero errors"
Check: Denominator cohort can return empty results
Solution: Add validation or use count indicators
🔧 Parameter Problems
Issue: "Required parameter not showing"
Check: Parameter type configuration
Check: User permissions for parameter type
Solution: Verify parameter definition and user rights
Issue: "Date picker not working"
Check: Parameter type is set to "Date"
Check: HTML Widgets module is installed
Solution: Reinstall HTML Widgets or use text input
📈 Report Performance Issues
Issue: "Report takes too long to run"
Causes: Large date ranges, complex SQL, system load
Solutions:
Optimize SQL queries
Add database indexes
Break into smaller reports
Schedule during off-peak hours
Issue: "System becomes unresponsive"
Causes: Memory issues, concurrent reports
Solutions:
Increase Java heap size
Limit concurrent report executions
Monitor system resources
Getting Help
Escalation Path
Check Documentation: Review this guide and OpenMRS wiki
Test Simplified Version: Remove complexity to isolate issues
Check Logs: Review OpenMRS application logs
Community Forums: Search OpenMRS Talk for similar issues
Expert Consultation: Contact module developers or consultants
Information to Gather
For Bug Reports:
OpenMRS version and module versions
Exact error messages
Steps to reproduce the problem
Sample data that triggers the issue
System configuration details
For Performance Issues:
Report complexity (number of cohorts, indicators)
Date ranges typically used
Number of patients in system
System specifications (RAM, CPU, database size)
Concurrent user load