Common Issues

Connection issues

Authentication failed — invalid API key

Double-check that you copied your full API key from CommCare HQ without any extra spaces. To find it, log in to CommCare HQ, click your username in the top right, go to Settings, and look for the API Key section. If you've recently regenerated your key, make sure you're using the new one.

Project Space not found

The Project Space name must match exactly what appears in your CommCare HQ URL — for example, if your URL is www.commcarehq.org/a/my-project/, the project space is my-project. It's case-sensitive and must not include slashes.

Connection works but returns no data

Check your start date setting. If you've set a start date far in the future, no records will match. Use the date picker to set a date in the past — at least far enough back to capture some submissions — and run the data flow again.

Missing data

Some form submissions are missing from the export

CommCare processes submissions asynchronously, so there can be a delay between when a form is submitted offline and when it appears in the API. If a mobile worker had poor connectivity, their submissions may arrive hours or days later. Use a start date that gives enough buffer to capture delayed syncs.

Case properties I expect are not showing up as columns

Case properties in CommCare are dynamic and depend on your app configuration. If a case has never had a particular property set, it won't appear as a column. Check that the cases in your export have actually had those properties filled in via a form submission.

Closed cases are not appearing in the export

By default, the Cases entity returns all cases including closed ones. If closed cases are missing, verify that your CommCare HQ API access level allows retrieving closed cases — this can vary by plan.

Permission errors

403 Forbidden error when running the data flow

This usually means your CommCare account does not have API access enabled. CommCare requires a Standard plan or higher to use the API. Check your CommCare HQ subscription, or contact your project administrator to confirm your account has the right permissions.

Can only see some cases or forms, not all

Your CommCare user account may only have access to cases owned by your user or group, not the entire project. Ask your CommCare project admin to grant your API user account project-level data access.

Data discrepancies

Row counts don't match what I see in CommCare HQ

CommCare HQ's reporting interface sometimes excludes test submissions or archived records. The API may return more rows than the UI shows. Check whether test users or test submissions are included in your export and filter them out in your destination if needed.

Dates look incorrect or are in the wrong timezone

CommCare stores timestamps in UTC. If your reports expect local time, you'll need to convert the timestamp columns in your destination (e.g., using a formula in Google Sheets or a transformation in BigQuery).

Rate limits

Export is very slow or times out for large projects

CommCare's API can be slow for projects with tens of thousands of forms or cases. Use the start date filter to limit the volume of records per export. For large historical datasets, consider breaking exports into smaller date ranges using separate data flows and using the Append transformation to combine them.