5.3.0 release notes

Released 2026-08-31

Highlights

Archiving

Long running or very active deployments can be overwhelmed with huge document counts. Many of these documents in CouchDB might no longer be relevant in day to day operations: CHWs might not need them and analytics in CHT Sync and couch2pg have already aggregated them. However, every CHT upgrade will process these older docs, increasing CPU usage and lengthening upgrade times. Outside of upgrades, CouchDB indexes will track all the older docs, ever increasing disk space and CHWs logging in for the first time will need to download years worth of data.

CHT 5.3 introduces archiving as the first step to addressing these issues. A new API endpoint has been added which allows CHT administrators to provide a list of documents for the server to archive. Documents archived by the CHT server are not deleted, but instead are moved out of the main database into a separate archive database on the same CouchDB instance. No data leaves the server as a part of the archiving process. The archived data remains stored on the same data volume as the rest of the CouchDB data but is not included in the indexes of the main database. Users will not have access to archived data (and it will not be reflected in the calculations for tasks/targets/contact-summary). This results in lower overall disk space usage (because the CouchDB indexes are smaller), decreases upgrade times, and decreases first time times for users. Existing data in CHT Sync and couch2pg remains untouched, ensuring business analytics numbers don’t change.

Read more in the documentation or the original GitHub issue.

CHT Watchdog showing a over 100,000 documents archived

Reducing hosting total cost of ownership

Along with the high document counts highlighted above, disk space remains one of the key pain points CHT administrators face when running CHT over longer periods. CHT 5.3 adds index improvements that reduce the time and extra disk space used during upgrades after upgrading to 5.3.

See the original GitHub tickets for more details.

Contact card photos

Alongside photo attachments for sub-contacts, the CHT can now be configured to display a small thumbnail for each contact. Seeing a face rather than just a name helps CHWs quickly recognize the people they serve, and photos also make it easier to distinguish between patients with similar or identical names. This feature was both requested and built by the community.

See “Profile image” docs and the GitHub ticket for more informationi.

A contact card showing a small picture of the contact

Photos on Sub-contacts

CHWs often need to fit many visits into an already busy day, so anything that speeds up form entry makes a real difference. Community members requested the ability to attach a photo to a sub-contact directly while registering a new household. Bringing this step into the registration flow saves time and eliminates the need to reopen each contact afterward just to add a photo. This is complementary feature of the contact card photos which enables the photo to easily be populated upon registration.

See the sub-contact docs and GitHub ticket for more info.

External datasets in forms

Deployments that rely on large choice lists in their workflows previously had no way to reuse those lists across forms. A list with hundreds of options used in 10 forms meant CHWs had to download it 10 times, significantly increasing sync times whenever the list changed. Administrators faced a parallel burden: a single update had to be carefully propagated across all 10 copies.

CHT 5.3 greatly simplifies this by enabling list reuse across forms. These shared datasets are declared once in app settings and can then be used as many times as needed. This feature was requested by the community and now arrives to meet that need.

For more info on how to implement this feature see the docs on “Select choice from file” or for a deeper dive, check out the GitHub ticket.

Improved GPS data on contacts forms

GPS metadata has been a part of the CHT for quite some time. However, prior to 5.3, it was opaque to the CHW the status of the GPS data. As well, if a contact form for a household was filled out in another location away from the househould, GPS data in the CHT could be innacurate.

5.3 adds support for showing a status widget in contact forms for capturing the GPS location at the time a contact is created or edited. The geolocation widget handles the full capture experience automatically: it starts acquiring a position the instant the form renders, then shows progress, success, and failure states. It stores the result on the contact document.

After a successful capture, the widget asks whether the CHW is at the household or somewhere else, and records the answer alongside the coordinates.

See the “Capture GPS Location in Contact Forms” docs or the GitHub ticket.

GPS failure with suggestions on how to fix

GPS Success with options on how to store

CHT Conf complimentary upgrades

Upgrading CHT Conf to 6.6.0 or later is strongly recommended. This version includes fixes for bugs surfaced during CHT 5.3 development, particularly around new features such as photos on sub-contacts and complex forms. To upgrade, run npm update -g cht-conf, or see the CHT Conf docs for detailed instructions.

See the CHT Conf releases to get a full list of fixes and improvements.

Increase recommended Android memory and CPU

The recommended Android specs have increased in CHT 5.3. This is not due to 5.3 changes, but reflect suggestions from Google and the CHT Community at the time of the 5.3 release. Minimum specs have not changed. See requirements for more info.

Known issues

Check the repository for the latest known issues.

Upgrade notes

Breaking changes

None.

UI/UX changes

#10662: Display uploaded image on client’s profile
#10676: Store geolocation when submitting contact forms
#10700: Support Photo Capture for Sub-contacts Within Parent Registration Forms
#11184: Update 3 filter UIs match each other: tasks, reports & targets

And more…

Features

#10662: Display uploaded image on client’s profile
#10676: Store geolocation when submitting contact forms
#10700: Support Photo Capture for Sub-contacts Within Parent Registration Forms
#9875: Support selecting from external dataset in forms

Improvements

#10707: Enhance Bikram Sambat support in CHT
#10847: Allow searching contacts by local phone number format without country code prefix
#11174: Add document-returning getPage / getAll to Contact.v1 and Report.v1
#11184: Update 3 filter UIs match each other: tasks, reports & targets
#8793: Block access for users with Chrome < 74
#9725: “Unexpected Error” Dialog due to global database failure should not be optional

Security fixes

None.

Performance improvements

#10651: Optimize indexes to reduce disk use and speed up upgrades (Hosting TCO)
#11125: Distribute nouveau across all couch nodes in multi-node deployments
#6615: Consider moving outdated documents to “cold storage” (Hosting TCO)

Bug fixes

#10851: Searching with Devanagari numerals no longer cross-matches Latin numeral contacts for online users (regression from 4.x)
#10963: Invalid config parsing in authorization.js leads to silent failures and unclear logging
#11218: Flaky e2e test: users doc count should return the configured limit and a log for every user:
#11241: Bikram Sambat (Nepali) date changes at 6:15 PM instead of local midnight
#11242: Mobile date tooltip clipped off the left edge of the viewport (report detail)
#11326: Deleted infodocs can cause an infinite loop in transitions
#11372: Contacts list shows raw translation key contact.last.visit.unknown for never-visited contacts in UHC mode
#7627: Memory leak caused by using the countdown-widget and the geopicker widget in the same form

Technical improvements

#10875: Flaky api integration tests: transitions
#10903: sub-contact photo capture: Contacts core routing + validation + unit tests
#10953: Memory leak: unmanaged store subscription in FastActionButtonComponent constructor
#11151: Add byForm qualifier to Report.v1 (replaces medic-client/reports_by_form page query)
#11194: Improve flaky test resolution process
#11289: Consistently failing e2e test: Webapp submits new GT sms messages should update SMS statuses
#11292: Develop a GH action BOT that adds automated messages to PRs
#11302: Publish helm chart to public URL
#11363: create helm 5.3 charts, ensure release dates are correct in helm index.yaml
#11370: Refactor reports-by-contact indexing to be done in docs_by_replication_key

Contributors

Thanks to all who committed changes for this release!

Last updated on August 28, 2026

Did this documentation help you ?

5.2.0