DHIS2 Troubleshooting¶

Use this guide when a DHIS2 connection, synchronization, site mapping, indicator configuration, or project performance view is not working as expected.

The troubleshooting process should normally follow the same order as the DHIS2 integration workflow:

Connection → Metadata → Site Mapping → Project Indicators → Reporting Data → Performance → Follow-up

DHIS2 connection problems¶

FieldOps cannot connect to DHIS2¶

If the DHIS2 connection test fails, first verify the connection details.

Check:

DHIS2 Base URL
Authentication type
Username and password, if using username and password authentication
Personal Access Token (PAT), if using PAT authentication
Whether the DHIS2 server is accessible
Whether the DHIS2 account is active
Whether the account has sufficient permissions

FieldOps supports two authentication methods when creating a DHIS2 connection:

Username & Password
Personal Access Token (PAT)

Make sure the credentials entered match the authentication method selected for the connection.

Username and password authentication fails¶

If you selected Username & Password, verify:

The username is correct
The password is correct
The DHIS2 account is active
The account can sign in to the DHIS2 server
The DHIS2 server accepts username and password authentication
The account has permission to access the required DHIS2 resources

If the credentials were recently changed in DHIS2, update the FieldOps connection with the new credentials and test the connection again.

Personal Access Token authentication fails¶

If you selected PAT, verify:

The token is correct
The token has not expired
The token has not been revoked
The token belongs to an account with the required DHIS2 permissions
The Base URL points to the correct DHIS2 server

If the PAT has been replaced or revoked, update the FieldOps connection with the new token and test the connection again.

Warning

Treat DHIS2 passwords and personal access tokens as credentials. Do not share them in screenshots, support tickets, public messages, or documentation.

The Base URL is incorrect¶

The Base URL must point to the DHIS2 server that FieldOps should connect to.

Check that:

The URL is correct
The server is accessible
The URL points to the intended DHIS2 environment
Development and production servers have not been confused

For example, if your organization maintains separate environments, make sure the FieldOps connection is pointing to the intended environment.

Connection test succeeds but synchronization fails¶

A successful connection test confirms that FieldOps can communicate with the DHIS2 server.

It does not necessarily mean that the connected account has permission to retrieve every resource required for synchronization.

If synchronization fails after a successful connection test, check the DHIS2 user's permissions.

The account may need access to the relevant:

Organization units
Data elements
Data sets
Indicators
Reporting data

Review the synchronization error message for additional information.

Metadata synchronization problems¶

No organization units appear after synchronization¶

If no DHIS2 organization units are available after synchronization:

Confirm that the DHIS2 connection test succeeds.
Confirm that metadata synchronization completed successfully.
Confirm that the DHIS2 account can access organization units.
Check whether the DHIS2 instance actually contains organization units.
Run the metadata synchronization again if required.

If the synchronization completes successfully but expected organization units are still missing, verify the DHIS2 account permissions and the source DHIS2 instance.

No indicators appear after synchronization¶

If DHIS2 indicators are not available in FieldOps:

Confirm that the DHIS2 connection is working.
Run DHIS2 metadata synchronization.
Confirm that indicators exist in the connected DHIS2 instance.
Confirm that the DHIS2 account can access the indicators.
Check whether the indicators are active in DHIS2.

Note

Synchronizing DHIS2 indicators makes them available to FieldOps. It does not automatically add every indicator to every project.

Project indicators must be configured separately.

Metadata appears outdated¶

If the DHIS2 metadata displayed in FieldOps appears outdated:

Confirm that the DHIS2 connection is active.
Run DHIS2 metadata synchronization.
Check the project's DHIS2 Sync Health section.
Review the Last Synchronized timestamp.

The synchronization timestamp helps confirm when FieldOps last recorded a successful metadata synchronization.

Site mapping problems¶

A FieldOps site cannot be mapped¶

If a site cannot be mapped to a DHIS2 organization unit, check:

The site belongs to the correct project
DHIS2 metadata synchronization has completed
The expected DHIS2 organization unit exists
The organization unit belongs to the intended DHIS2 connection
The DHIS2 organization unit has not been removed or changed in DHIS2

The wrong organization unit was mapped¶

If a site was mapped to the wrong DHIS2 organization unit:

Open the site's DHIS2 mapping.
Review the selected DHIS2 organization unit.
Select the correct organization unit.
Save the mapping.
Review the project's DHIS2 performance again.

Warning

Incorrect site mapping can cause FieldOps to display DHIS2 reporting data for the wrong location.

A mapped site has no DHIS2 data¶

If a mapped site appears under Sites Without Data, check:

The FieldOps site mapping.
The selected DHIS2 organization unit.
The project indicator configuration.
The DHIS2 reporting period.
Whether the DHIS2 organization unit has data for that period.
Whether reporting data has been synchronized.

A missing value does not automatically mean that the site failed to report.

Project indicator problems¶

A DHIS2 indicator is available but cannot be selected for a project¶

First confirm that the indicator has been synchronized from DHIS2.

Then check:

The indicator belongs to the intended DHIS2 connection
The indicator is active
The project is using sites mapped to the relevant DHIS2 connection
The indicator has not already been added to the project

FieldOps prevents the same DHIS2 indicator from being added to the same project more than once.

The indicator appears in the project but has no performance result¶

Check:

The indicator is active for the project
The project has mapped sites
The sites are mapped to the correct DHIS2 organization units
DHIS2 contains data for the reporting period
Reporting data has been synchronized

The indicator has data but is not classified as On Target¶

Check the project's indicator configuration.

Review:

Target value
Target direction

For example, if the indicator is configured as:

Target: 80%
Direction: Higher is better

then:

Actual: 85%

should be interpreted as meeting the target.

If the direction is incorrectly configured, the performance classification can also be incorrect.

Target configuration problems¶

The indicator shows "No Target"¶

A performance record shows No Target when no project-specific target has been configured for the indicator.

To resolve this, configure a target for the project indicator.

For example:

Indicator: Immunization Coverage
Target: 80%
Direction: Higher is better

Note

DHIS2 indicators can exist without a FieldOps project target. FieldOps uses the project-specific target when evaluating performance.

The target direction is incorrect¶

FieldOps supports:

Higher is better
Lower is better

Use Higher is better when increasing values represent improved performance.

Use Lower is better when decreasing values represent improved performance.

For example:

Higher is better

Immunization coverage

Lower is better

Stock-out rate

Review the project indicator configuration if performance results appear to be interpreted incorrectly.

Reporting data problems¶

Sites are mapped but show no data¶

If mapped sites appear under Sites Without Data, investigate in this order:

Confirm the site mapping.
Confirm the project indicator.
Confirm the reporting period.
Confirm that the DHIS2 organization unit contains data.
Confirm that reporting data has been synchronized.

This helps determine whether the issue is caused by mapping, configuration, missing DHIS2 data, or synchronization.

Some sites report while others do not¶

This can occur when:

Some sites have submitted data and others have not
Some DHIS2 organization units contain data while others do not
Some site mappings are incorrect
Data for the sites is incomplete
The relevant reporting data has not been synchronized

Compare the affected sites with sites that are reporting successfully.

If only specific sites are affected, check their individual DHIS2 mappings first.

DHIS2 Performance problems¶

The DHIS2 Performance section does not appear¶

The DHIS2 performance section is displayed conditionally.

It appears when the project has an active DHIS2 integration.

If it does not appear, check whether the project has at least one active DHIS2 project indicator.

Performance numbers appear to be incorrect¶

Review:

Reporting period
Mapped sites
Active project indicators
Indicator targets
Target directions
Available DHIS2 data

Also confirm that the correct DHIS2 connection and organization units are being used.

Sites Reporting is lower than Sites Mapped¶

This means that some mapped sites do not have the expected DHIS2 reporting data for the reporting period.

Review the Sites Without Data information and investigate those sites individually.

Below Target is unexpectedly high¶

Check the project indicator configuration.

For each affected indicator, verify:

Target value
Target direction
Actual DHIS2 value
Reporting period

An incorrectly configured target or direction can cause expected performance results to be interpreted incorrectly.

Action Required problems¶

A site appears under Action Required¶

A site appears in the Action Required section when one or more tracked DHIS2 indicators are below the configured project target.

Review:

Site
Indicator
Actual value
Target
Target direction
Reporting period

If the result is expected, the monitoring team can record a finding and create a follow-up action.

A site is not appearing under Action Required¶

If an expected site is not listed:

Confirm that the indicator is active for the project.
Confirm that a target is configured.
Confirm that the target direction is configured.
Confirm that the site is mapped.
Confirm that DHIS2 data exists for the reporting period.
Review the actual value against the target.

An indicator without a target cannot be evaluated as below target.

Findings and follow-up problems¶

A performance issue requires follow-up¶

If a DHIS2 performance result requires formal monitoring attention:

Review the performance result.
Record a finding in FieldOps.
Set the appropriate severity and status.
Add a follow-up action.
Assign the responsible person.
Set a due date where appropriate.
Track the action.
Resolve and close the finding when appropriate.

The workflow is:

DHIS2 performance → Finding → Action → Accountability

A finding exists but no action has been created¶

A finding and an action are separate parts of the FieldOps workflow.

A finding records the issue.

An action records the response required to address the issue.

If a response is required, open the finding and add the appropriate follow-up action.

DHIS2 Sync Health problems¶

Sync Status shows "Not synchronized"¶

This means that no successful synchronization has yet been recorded for the relevant DHIS2 connection.

Check:

The DHIS2 connection
Connection credentials
Connection test status
Metadata synchronization
Synchronization errors

Run the required synchronization after resolving any connection problems.

Sync Status shows "Attention"¶

An Attention status indicates that the relevant DHIS2 integration requires investigation.

Check:

The relevant DHIS2 connection.
Connection test status.
Connection credentials.
Last synchronization.
Synchronization errors.
Site mappings.

If the organization uses multiple DHIS2 connections, check each connection relevant to the project's mapped sites.

Sync Status shows "Healthy" but data is missing¶

A healthy synchronization status does not guarantee that every reporting value exists.

A connection can be healthy while:

A site has not reported
An indicator has no value for the reporting period
A site is mapped incorrectly
The reporting period contains incomplete data

Use the performance and site mapping information to investigate the missing data.

Multiple DHIS2 connections¶

An organization can have multiple DHIS2 connections.

For example:

Kenya DHIS2
Uganda DHIS2
Production DHIS2
Development DHIS2

A project may use one or more of these connections through its mapped sites.

If a project has unexpected DHIS2 results, verify which DHIS2 connection each site's mapping uses.

Note

FieldOps determines project-level DHIS2 connection information from the connections associated with the project's mapped sites. It does not assume that the organization has only one DHIS2 connection.

When to re-synchronize metadata¶

Consider running DHIS2 metadata synchronization when:

New DHIS2 indicators have been created
New organization units have been created
Existing DHIS2 metadata has changed
A new DHIS2 connection has been configured
Expected indicators are missing from FieldOps
Expected organization units are missing from FieldOps

After synchronization, review the relevant project configuration again.

Recommended troubleshooting order¶

When a DHIS2 problem occurs, use this order:

1. Check the connection¶

Confirm that FieldOps can communicate with the DHIS2 server.

2. Check synchronization¶

Confirm that the required DHIS2 metadata has been synchronized.

3. Check site mapping¶

Confirm that the FieldOps site points to the correct DHIS2 organization unit.

4. Check project indicators¶

Confirm that the expected indicator is active for the project.

5. Check targets¶

Confirm that the target value and target direction are correct.

6. Check reporting data¶

Confirm that DHIS2 contains data for the relevant organization unit and reporting period.

7. Check performance¶

Review the project's DHIS2 Performance section.

8. Check follow-up¶

If a performance issue is confirmed, record a finding and create a follow-up action where required.

Quick troubleshooting checklist¶

Problem	First thing to check
Cannot connect to DHIS2	Base URL and authentication credentials
Username/password fails	DHIS2 account credentials and permissions
PAT fails	Token validity and permissions
Indicators missing	Metadata synchronization
Organization units missing	Metadata synchronization
Site has no data	Site mapping and reporting period
Indicator shows No Target	Project indicator target
Performance classification is wrong	Target direction
Sites Reporting is low	Sites Without Data and mappings
Action Required is unexpected	Target and target direction
Sync Health shows Attention	DHIS2 connection status
Sync Health shows Not synchronized	Successful metadata synchronization
Performance section missing	Active DHIS2 project indicator
Finding needs follow-up	Add an action to the finding

What to do next¶

If the problem cannot be resolved using this guide, collect the relevant error message and review the DHIS2 connection, synchronization, mapping, and project configuration before contacting support.

Connect DHIS2

Synchronize DHIS2 Metadata