CommCare Android Troubleshooting

Owned by Clayton Sims
Last updated: Apr 19, 2024 by Gillian Javetski
11 min read

This page describes some actions that can be useful for troubleshooting CommCare Android when the application ends up in a bad state.

If you are unable to solve your problem and do end up submitting a ticket to the CommCare support team, please make sure to include information from the error itself, per here: https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143956620.

Starting Fresh

Force Full Refresh

Due to synchronicity or updates between the server and the phone, the phone can end up with stale or incompatible data.

To force a full refresh of the user's data, you can navigate to the Mobile Worker's page on CommCare HQ. You can do so by clicking on Users > Mobile Workers via the ribbon menu.

Select the username of the mobile worker.

Under the Actions tab click Force Full Refresh on next Mobile Sync.

For each device the mobile worker is on (including Web Apps), this will make it so the next time they sync that device, it will do a Full Refresh of data instead of an incremental sync. This includes case data and fixture data (including lookup tables).

The Full Refresh operation is generally recognized as safe, and happens automatically during 1-2% of restores, when irregularities are auto-detected. However there are a few caveats to keep in mind:

  • A full refresh can sometimes take longer than an incremental sync. For the majority of projects, this is negligible. If your users are able to install the app on their normal internet connection, then this will certainly not be an issue. If however you have a very large case load or very large lookup tables that affects users' ability to install the app from the field, a full refresh may be subject to the same issues.

  • Incomplete forms on Web Apps for this user will be deleted the next time they sync.

If in the past you have used User Data Reset, you are strongly encouraged to use this feature instead in those situations.

User Data Reset (aka Clear User Data)

Use Force Full Refresh instead whenever possible. If you have no access to CommCare HQ, all data can be wiped locally instead, but it comes with fewer safety checks. Please note that this can result in some data loss if you have valid unsent forms.

On 2.28 and higher:

1. Log into CommCare.

2. Look at the Sync with Server button on the home screen. If it says Unsent Forms click on the button to submit those forms to the server.

3. When on the CommCare Home Screen, Press the Menu button on your phone and choose the "advanced" option. (On a Samsung or a LAVA, Menu is the bottom left button).

4. Press Clear User Data.

5. You will be returned to the login screen. Re enter your username and password and your user data will be re-synced to the device.

          

Fresh Restart

It is occasionally possible to end up putting the phone into a state which needs to be recovered from the cloud, resetting the local install. This is also helpful once problems are diagnosed, but before a fix can be prepared. The steps for doing so are:

Make sure that you have the reference to your application's profile QR Code before starting, as well as the appropriate credentials for the user on the phone.

  1. Make sure any local data is uploaded.

    1. Log in to CommCare with your username and password, and ensure that the application isn't loading a screen informing you that it is sending unsent forms.

    2. Log back out.

  2. Clear the local memory on the phone

    1. Navigate to the phone's applications management menu, generally from the home screen the process is Options -> Settings -> Applications -> Manage Applications.

    2. Navigate to CommCare Android.

    3. Press Clear Data and confirm.

  3. Reinstall your specific app.

    1. Load up a barcode scanner on the device.

    2. Scan the barcode for your application and confirm to navigate to it with CommCare.

    3. Press the install button on CommCare, the screen will freeze but eventually load the login screen

  4. Restore User Data.

    1. Log in with the username and password as usual. Since the restore is clean, it may take somewhat longer than usual.

CommCare Mobile Error Messages

“A serious problem occurred while CommCare was trying to download an update (or install your app): CommCare couldn't find the resource with id: commcare-application-profile.”

This message, which can show up upon installation, is often due to a bad internet connection. This almost always means you do not have a strong enough Internet connection. Make sure you have Internet access.

“Unfortunately, CommCare Android has stopped.”

If CommCare crashes and you get this message, you can get more detailed information about the nature of the problem by doing the following: 

  • When CommCare crashes click the 'Report button' in the crash dialog.

  • Once the crash report has loaded click on the 'Preview' button.

  • Scroll to the bottom and click on 'Stack Trace'.

  • In the stack trace you should be able to find a more detailed error message.

“Storage is Corrupt :/”

CommCare Android can enter an error state with the message "Storage is Corrupt :/" (see image at bottom). This happens when the app install that's currently on the phone enters an inconsistent state that we can't correct.

There are three causes of this

  • The app's storage files have been manually changed/modified: Some of CommCare's files non-userdata files are stored on the phone in an area where external apps can delete them.

  • The phone's storage layer has corrupted the files stored to the device: This is a problem that we've seen on certain devices, more commonly with counterfeit SD Cards. We don't believe this to be a common problem outside of Counterfeit SD cards, but it has come up in the past rarely.

  • There is a bug in CommCare's code that is resulting in corrupted files: It's possible that CommCare is writing an invalid app structure to the phone's storage due to an unforseen bug in the code. The only time this kind of bug could occur that would result in Recovery Mode being triggered would be immediately after some sort of remote update that resulted in the phone not having a fully installed and consistent version of your app. This would not be expected, however, to cause any problems in submitting unsent data to the server. 

If you receive this error, please report it! In your report, please let us know:

  1. What version of CommCare you are using - So we know whether it's possible that you are triggering an older bug

  2. What devices are in use: This helps us disambiguate whether the issue might be related to "external storage" on older android phones and also the likelihood that there might be any hardware problems.

  3. Whether there was a specific circumstance that seemed to trigger the issues. Are you frequently using remote updates for the app? Do you know whether the issues appeared after some critical event?

  4. How widespread is the issue? Do certain users seem to have the problem over and over, or is it randomly distributed between users? 

  5. Can you replicate the problem? If so we can help work through it very quickly.

CommCare Recovery Mode

Phones entering recovery mode is unusual and unexpected. This happens when the app install that's currently on the phone enters an inconsistent state that CommCare can't correct.

Selecting "Enter Recovery Mode" will navigate you to a screen like the one below. An advantage of entering recovery mode is that users will be presented with the opportunity to submit any unsent forms.

“Having issues communicating with the server to send forms. Will try again later” or “CommCare ODK will not Send Forms to Server”

We have recently encountered a few instances where one device or user on a domain is not able to send forms to the server despite a seemingly strong internet connection.

Unfortunately this is often the result of SSL certificate errors, firewalls, or other issues that we have trouble diagnosing and fixing. Please submit a support ticket when you receive this. For an immediate fix, you can try using https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143973390 to transfer your forms to another device. Please follow the links above to see instructions on using this feature. The forms you send via these methods will appear the same on the server as if they had been submitted by the original device.

"The case sharing settings for your user are incorrect. This user must be in exactly one case sharing group. Please contact your supervisor"

Or via Web Apps:

Before we can debug this error it's important to understand a few relevant concepts:

  • Case sharing - if an app has Case Sharing enabled, cases are supposed to be shared between users. For more on this, see https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143957537.

  • Case Ownership - every case in CommCare has an owner that can be a user (web or mobile), a user group or a location, which means that before a case can be created its ownership needs to be decided. The decision of who (or what) should be the owner is normally done by CommCare but can also be done manually, as we will explain later. However, when Case Sharing is enable this process becomes complex for CommCare as the User, the default option, is no longer acceptable.

Let's now interpret the error. Mainly, Case Sharing is enabled and CommCare is responsible for determining the owner of cases. However, the user is either configured incorrectly or they are associated with too many locations and/or case sharing groups, so CommCare gets "confused" and throws this error. Often, this can be solved by setting the ownership manually. An important note here is that, in most of the scenarios this error is directly related to some design decision made for the app, so before implementing a solution, it's good practice to revisit documentation to ensure that whichever solution is applied won't break any workflow.

The following is a list of example scenarios that could lead to this error coming up:

  1. User is not assigned to a Location or Case sharing group - without a Location or Case Sharing Group associated to the mobile user, CommCare is forced to set the ownership to the user. However, setting the ownership to the user will automatically prevent the case from being shared, so CommCare prevents this behavior from happening automatically.

    1. Solution: assign the user to a Location or a Case Sharing Group

  2. User is assigned to more than one case sharing group and/or location - considering that there are many options available, CommCare is unable to decide on who should be the rightful owner, resulting in that same error being thrown. This also applies if the user is assigned to one Case Sharing Group and one Location when the Organizational Level is set to Own Cases (see more in ).

    1. Solution: There are two potential approaches here. You can change the configuration of the user so that they are only assigned to a single Case Sharing Group (see more in ) or Location (see more in ). Alternatively, you set the ownership manually within the form (see below).

  3. User is assigned to a Location that can't Own cases - in this scenario, CommCare sees that the user is assigned to a Location that, according to the configuration of the Organization Level, can't own Cases.

    1. Solution: There are two potential approaches here. You can change the configuration of the location to allow it to own cases (see more in ), or you can set the ownership manually (see below). You will need to ensure that all cases created within the form settings have an owner_id property set, including any child cases.

  4. User is assigned to a Location with child Locations and View Child Data is Enabled - this is a more complex problem to solve. In this case, it typically appears that the users are correctly configured, and that each one is assigned to a single location. However, since the user has access to data in the child locations as well, the child locations are also considered valid candidates for case sharing, similarly to if the user was actually assigned to multiple locations as outlined above.

In this example, we can conclude that Nurse should be able to see cases from their CHWs and also to have their own cases. The error would occur when Nurse tries to create a new case, however, the app should work fine for CHW 1 and 2.

a. Solution: In this case, usually the only viable option is to set the ownership manually (setting a hidden value in the form called owner_id, manually setting it to be the location you need the case to live at, and saving it as a case property). Of course, you could turn the View Child Data option off but this would most likely go against the workflow of the app.  

Setting case ownership manually 

So, at this point it's safe to assume that you have exhausted all other options and decided to set the ownership of the case manually. First, you need the ID of the owner, this can be achieved either by having the user selecting a Location or a Case Sharing group from a Multiple Choice Lookup Table question or some calculation that returns a single ID. Next, you need to instruct CommCare to assign the ownership based on that ID, for that you have to set the case property owner_id in the Case Management section of your form. Find more information about this process under

Stuck Forms

How to fix incomplete forms that can be loaded

See .

How to check if there are quarantined forms on the device

If you know or suspect that there are forms which a mobile user filled out on their device but are not appearing on the server, one possible cause is that the form became corrupted in some way and has been quarantined on the device. Quarantining is when the form gets removed from the queue of forms to be sent to CommCare HQ, but is still kept on the device. If CommCare Android detects that a form has become corrupted, it will automatically quarantine the form. Users can also manually quarantine a completed-but-unsent form. You can view quarantined forms on a device by taking the following steps:

1. Go to the list of Saved Forms on the device, either by pressing the "Saved" button on the home screen (if it's available), or going to the home screen options menu and then selecting "Saved Forms". 

2. Click on the filter button in the upper-right corner of that screen, and select "Filter: Quarantined Forms."

3. If there are any quarantined forms on the device, they will appear in this list, and you will be able to open them for viewing to determine what exact form they were.

4. You can also get more information about what is wrong with a quarantined form by long-clicking on the form in the list, and then selecting "Scan Record Integrity". A dialog will then pop up with some detailed information about the form and what may be wrong with it. This information can be quite dense, but it is very helpful to include if you are reporting an issue to Dimagi about the problematic form.