KoboToolbox Troubleshooting¶
Use this guide to resolve common problems when connecting KoboToolbox to FieldOps, creating form mappings, or synchronizing submission data.
Connection problems¶
FieldOps cannot create the KoboToolbox connection¶
If FieldOps cannot connect to KoboToolbox, check the connection details.
Confirm that:
- The Base URL is correct
- The API token is correct
- The API token belongs to an active KoboToolbox account
- The KoboToolbox account is accessible
- Your FieldOps organization has not reached its Kobo connection limit
For most KoboToolbox accounts, the Base URL is:
If your organization uses another KoboToolbox server or a self-hosted deployment, use the Base URL for that server instead.
Tip
Check for extra spaces when copying the Base URL or API token into FieldOps.
The API token is not working¶
Make sure that:
- You copied the complete API token
- There are no extra spaces before or after the token
- The token belongs to the KoboToolbox account containing the required forms
- The token has not been replaced or revoked
If necessary, obtain the API token again from your KoboToolbox account and update the connection in FieldOps.
Warning
Treat your KoboToolbox API token like a password. Do not include it in screenshots, support messages, or public documentation.
The wrong KoboToolbox server was used¶
The Kobo Connection determines which KoboToolbox server FieldOps communicates with.
For most standard KoboToolbox accounts, use:
https://kf.kobotoolbox.org
If your account is hosted on another KoboToolbox server, use the Base URL for that environment.
A valid API token for one KoboToolbox environment may not work with another server.
Form mapping problems¶
The Kobo Connection is not available when creating a form mapping¶
A Kobo Connection must be created before you can create a Kobo Form Mapping.
Confirm that:
- The connection was created successfully
- The connection belongs to your active FieldOps organization
- You have permission to access the connection
Create a KoboToolbox connection
The Kobo Form ID is not working¶
FieldOps uses the KoboToolbox form's unique asset identifier as the Kobo Form ID.
A Kobo Form ID looks similar to:
ag8uJPUdTLrGSNdN5FHDKf
Open the form in KoboToolbox and check the browser URL.
If the URL contains:
/assets/ag8uJPUdTLrGSNdN5FHDKf/
enter only:
ag8uJPUdTLrGSNdN5FHDKf
into the Kobo Form ID field.
Check that:
- You copied the correct identifier
- You copied only the identifier and not the complete URL
- There are no extra spaces
- The selected Kobo Connection has access to the form
Warning
Do not enter the complete KoboToolbox URL into the Kobo Form ID field.
The form belongs to a different KoboToolbox account¶
The selected Kobo Connection must use an account that can access the form identified by the Kobo Form ID.
If the form belongs to another account or is not shared with the connected account, FieldOps may not be able to access its submissions.
Confirm that the KoboToolbox account associated with the API token has access to the form.
The Programme is not available¶
Confirm that:
- The required Programme already exists in FieldOps
- You are working in the correct FieldOps organization
- You have access to the Programme
Create the required Programme before completing the form mapping if necessary.
The Project is not available¶
Confirm that:
- The required Project already exists
- The Project belongs to the appropriate Programme
- You are working in the correct FieldOps organization
The Site is not available¶
Confirm that:
- The required Site already exists in FieldOps
- You are working in the correct FieldOps organization
- The Site is available for the mapping you are creating
No Monitoring Template is available¶
Selecting a Monitoring Template is optional.
If you do not have a suitable existing Monitoring Template, leave the field empty and continue creating the form mapping.
Synchronization problems¶
New submissions are not appearing immediately¶
FieldOps automatically synchronizes mapped KoboToolbox forms at regular intervals, typically about every 10 minutes.
A new submission may therefore take several minutes to appear in FieldOps.
If you want to synchronize immediately, use the Sync Now action on the Kobo Form Mapping.
Tip
After creating a new form mapping, use Sync Now to test the integration without waiting for the next automatic synchronization cycle.
Sync Now does not retrieve any submissions¶
Check that:
- The correct Kobo Connection is selected
- The Kobo Form ID is correct
- The connected KoboToolbox account has access to the form
- The form contains submissions
- The API token is still valid
- The form mapping has been created successfully
Also confirm that you are checking the correct FieldOps Programme, Project, and Site after synchronization.
Some submissions are missing¶
First confirm that the missing submissions exist in KoboToolbox.
Then:
- Wait for the next automatic synchronization cycle, or
- Use Sync Now to start synchronization immediately
If the submissions still do not appear, check that the form mapping uses the correct Kobo Form ID and Kobo Connection.
A submission already synchronized to FieldOps is updated in KoboToolbox¶
Allow the next automatic synchronization cycle to run or use Sync Now.
FieldOps uses the KoboToolbox submission identifiers when synchronizing external data so that previously synchronized records can be identified during later synchronization runs.
Automatic synchronization appears delayed¶
Automatic synchronization runs in the background at regular intervals, typically about every 10 minutes.
The exact time before new data appears may vary depending on:
- When the KoboToolbox submission was received
- When the next synchronization cycle starts
- The number of submissions being processed
- Background processing and queue activity
If the data is needed immediately, use Sync Now.
Data appears under the wrong Programme, Project, or Site¶
The Kobo Form Mapping determines the FieldOps context used for synchronized data.
Review the form mapping and confirm the selected:
- Programme
- Project
- Site
- Monitoring Template, if applicable
Warning
Review the mapping carefully before synchronizing a form. The selected Programme, Project, and Site determine where synchronized data belongs in FieldOps.
The connection previously worked but now fails¶
A previously working connection may stop working if:
- The KoboToolbox API token was changed or revoked
- The connected account lost access to the form
- The KoboToolbox server URL changed
- The form is no longer available to the connected account
Review the Kobo Connection and confirm that its credentials are still valid.
Before contacting support¶
Before requesting assistance, collect the following information:
- The name of the Kobo Connection
- The KoboToolbox Base URL
- The Kobo Form ID
- The name of the form
- Whether the problem occurs during connection, mapping, or synchronization
- The approximate time the problem occurred
- Any error message displayed by FieldOps
Warning
Never include your KoboToolbox API token when sharing troubleshooting information.
Screenshots can be helpful, but make sure they do not contain API tokens or other sensitive credentials.