Troubleshooting¶

Use this guide to resolve common problems when using FieldOps.

For integration-specific problems, see the dedicated troubleshooting guides for KoboToolbox and ODK Central.

Before you begin¶

Many issues can be resolved by checking:

That you are signed in to the correct FieldOps organization
That you have permission to perform the action
That the required Programme, Project, or Site has been created
That external integration credentials are still valid
That your organization's plan allows the feature you are trying to use

I cannot access a feature¶

FieldOps uses roles and permissions to control access to features.

If a page, resource, or action is not available to you, your assigned role may not have permission to use it.

Contact an organization Owner or Administrator if you believe you require additional access.

I am working in the wrong organization¶

FieldOps data and access are organization-scoped.

Before creating or managing data, confirm that you are working in the correct organization.

This is particularly important when working with:

Programmes
Projects
Sites
Monitoring Templates
Visits
KoboToolbox connections
ODK Central connections
Excel imports
BI Access Tokens

Data created in one organization is not automatically available in another organization.

I cannot create another resource¶

Your FieldOps plan may include limits on certain resources.

Depending on your plan, limits may apply to:

Users
Programmes
Projects
Sites
Visits
KoboToolbox connections
ODK Central connections
Excel imports
BI Access Tokens

If you have reached a plan limit, you may need to remove an unused resource or change your FieldOps plan.

A page or action is not loading¶

Try the following:

Refresh the page.
Confirm that your internet connection is working.
Sign out of FieldOps and sign in again.
Confirm that you are working in the correct organization.
Try the action again.

If the problem continues, contact FieldOps Support and include:

The page where the problem occurred
The action you were trying to perform
The error message, if one was displayed
The approximate time the problem occurred
A screenshot, if it does not contain passwords, access tokens, or other sensitive information

KoboToolbox connection problems¶

If FieldOps cannot connect to KoboToolbox, check:

The KoboToolbox Base URL
Your KoboToolbox credentials or token
That the KoboToolbox account is active
That the account can access the required form
That the correct Kobo connection was selected
That the Kobo Form ID is correct

Use Test Connection when creating or updating the connection to confirm that FieldOps can communicate with KoboToolbox.

For detailed guidance, see:

Troubleshoot a KoboToolbox connection

ODK Central connection problems¶

If FieldOps cannot connect to ODK Central, check:

The ODK Central Base URL
The ODK Central Project ID
The account email address
The account password
That the account has access to the required ODK Central project and forms
That the correct ODK connection was selected
That the ODK Form ID is correct

Use Test Connection when creating or updating the connection to confirm that FieldOps can communicate with ODK Central.

For detailed guidance, see:

Troubleshoot an ODK Central connection

Data is not synchronizing¶

If data from KoboToolbox or ODK Central is not appearing in FieldOps:

Confirm that the external connection is working.
Confirm that the correct form mapping exists.
Confirm that the external form contains submissions.
Review the mapping details.
Use Sync Now to request an immediate synchronization.

FieldOps also performs automatic synchronization at configured intervals.

Note

Synchronization may not be immediate when waiting for an automatic sync. Use Sync Now when you need to request synchronization immediately.

An Excel import contains failed rows¶

An Excel import can complete successfully while some individual rows fail validation or processing.

Review the failed rows to identify the problem.

After correcting the affected data, retry the corrected rows.

For detailed guidance, see:

Correct failed Excel rows

I cannot access the BI API¶

Check that:

You are using a valid FieldOps BI Access Token
The complete token was supplied
The token was sent as a Bearer token
The token has not been removed or revoked
You are using the correct production endpoint
The requested BI table exists

The authorization header should follow this format:

Authorization: Bearer YOUR_BI_ACCESS_TOKEN

For more information, see:

FieldOps BI API

My BI query returned fewer records than expected¶

FieldOps may apply safe query controls to broad or resource-intensive requests.

Inspect:

query_guard
pagination
meta

The response may indicate:

A safe result limit was applied
Additional pages are available
The request was served from an optimized BI dataset
The returned result is aggregated

For detailed guidance, see:

Query BI data

My BI query returned no data¶

Check that:

The organization associated with the BI Access Token contains the requested data
The BI table name is correct
The filters match existing records
The Programme, Project, Site, or User IDs are correct
The date range is correct

You can also inspect the available datasets and table schemas before building a query.

Discover BI datasets and schemas

I received an error message¶

Read the complete error message before retrying the action.

If the error identifies a specific problem, such as:

Invalid credentials
Missing required information
Permission denied
Plan limit reached
Invalid mapping
Invalid query

correct the identified problem and try again.

If the error continues, contact FieldOps Support.

Before contacting support¶

To help resolve the problem faster, collect the following information:

A short description of the problem
What you were trying to do
The page or feature where the problem occurred
The exact error message
The approximate date and time of the problem
The steps required to reproduce the issue
A screenshot, where appropriate

Warning

Never include passwords, KoboToolbox credentials, ODK Central passwords, BI Access Tokens, or other sensitive credentials in a support request or screenshot.

What to do next¶

If you cannot resolve the problem using the relevant troubleshooting guide, contact FieldOps Support.

Contact FieldOps Support