CommCare for Android Force Close from Loading Incomplete Forms

Owned by Gillian Javetski
Last updated: May 29, 2024 by Gillian Javetski
3 min read

This procedure is complex and if not carried out completely can cause complications. DO NOT do this if you have remote update enabled on many phones which are being used in the field as it will cause all of the phones to revert to an earlier version of the application

When CommCare Android users are storing incomplete forms on their devices and update to a newer version of the application, a situation can arise where an older incomplete form on the Android device is no longer compatible with the updated version of the form in the application.

For example, the old version of the form might have a multiple choice question with choices: "Boston", "New York", and "Washington". The mobile user opens this form and selects "Washington" as the answer, but then exits the form and saves it as incomplete.

Later, a new version of the application is deployed. The option "Washington" is removed and changed to "Philadelphia". The mobile user's device then updates to this new version.

Now when the mobile user tries to open the incomplete form, CommCare will attempt to load "Washington" as the answer, however, "Washington" is no longer a valid answer to the question. This causes the device to crash.

The solution in this situation is:

  1. Find an older version of the application in the release manager which is compatible with the older form

  2. "Revert" to that and make a new version. Now the latest version will be compatible with the older form

  3. Temporarily "star" that version

  4. On the device, click "Update CommCare" in the settings menu. This should update the device to the older version of your application.

  5. Open and complete the incomplete forms on the device and submit them to the server

  6. Once all the incompatible incomplete forms are submitted, revert to the version that should be the latest currently deployed version.

  7. Re-star the newest build and update to this one again.

Note that this will cause all of your phones with remote update enabled to update.

Users should be encouraged not to keep forms Incomplete for long periods of time. If they need to return to the form to complete it at a later date, you should add a separate form for the follow-up visit.

Alternative Solution

If you're in this situation but starring a new build is prohibitive due to possible accidental auto-updates in the field, there is an alternative solution available. This is slightly more difficult than the method above, but does not have the possible negative side affects to other phones in the project. It begins the same as the instructions above:

  1. Find an older version of the application in the release manager which is compatible with the older form

  2. "Revert" to that and make a new version. Now the latest version will be compatible with the older form

  3. Instead of "starring" this build, click "Deploy"

  4. On the pop-up that appears, right click the "Download CommCare.jad" link and select the "Copy link location" option (or the similar option in your browser)

  5. Paste this text into a text editor of your choice (like Nodepad++ or Word)

  6. In the URL you just pasted, copy the long hexadecimal code at the end of the URL after "download" and before "CommCare.jad" For example, https://www.commcarehq.org/a/willsproject/apps/download/04651630de172362e1e5e980fb6a7d04/ has code 04651630de172362e1e5e980fb6a7d04/

  7. On the problematic device, navigate to the home screen and hit the "Settings" button. On most devices this will be the three vertical dots in the top right corner of the screen.

  8. On this menu, select the "Settings" option

  9. On the next screen, select the "CommCare Application Server" option

  10. In the dialogue box that opens, copy down the long hexadecimal code here, then delete everything after the "/download/" part of the URL, including the hexadecimal code here and the "?latest=true" argument if its present

  11. Replace this with the code you copied from before

  12. Select "OK" and return to the home screen. From here, pull up the settings menu again and select "Update CommCare"

  13. CommCare should now update to the reverted version. Now you should be able to access your incomplete forms, finish them, and submit them to our server

  14. Once you are done with this, again follow instructions 3-10 but with the code from your most recent CommCare version (the one your copied in step 4).

  15. You should now be back to the version you started with.