20.5. Troubleshooting guide

The following table shows some common problems which occur and likely remedies:

Table 20.1. Troubleshooting guide


When you attempt to access the site with your browser it does not connect.

Either there is a network problem or nginx is not running. Check first to see if you can ping the host. If not you have a network problem. If you can ping the site, the most likely problem is that nginx is not installed or is not running. Verify that nginx is up and running and listening on ports 443 and 80 by typing:

sudo netstat -ntlp

You should see the nginx process listening on those 2 ports

You can access the site but you see a 502 gateway error in your browser.

This means that nginx is unable to connect to your backend dhis2 instance. Either the instance is not running or your nginx location configuration has an error. Running the same netstat command above should show your instance listening on with a port number typically 8080 or whatever you have configured it as.

If its not running, try to start it with dhis2-startup [instance name]

If it is still not running, check the log file with dhis2-logview [instance name] to see if there is any information indicating why it has failed to start.

If it is running and you can see it with netstat then you need to check your nginx configuration file to ensure that the locatio is correctly mapped.

You can access the site but you see a blank page in your browser.

This usually means that the dhis2 instance is running, but you have forgotten to deploy a war file to it. You need to run dhis2-deploy-war on that instance. See the reference section above for details of options.