Confirm infrastructure health
Check CPU, memory, disk space, network, DNS and operating-system services.
uptime
free -h
df -h
df -i
ip addr
getent hosts YOUR_DOMAIN
sudo systemctl --failedDiagnose Docker, database, Liquibase, Apache Fineract, Mifos Web App, Nginx, domain, SSL, authentication and API connection problems using a structured troubleshooting process.
Structured diagnosis
Start with infrastructure and dependencies. Do not investigate the frontend before confirming the database and Apache Fineract are healthy.
Check CPU, memory, disk space, network, DNS and operating-system services.
uptime
free -h
df -h
df -i
ip addr
getent hosts YOUR_DOMAIN
sudo systemctl --failedIdentify containers that are stopped, unhealthy or repeatedly restarting.
docker compose ps
docker ps -a
docker stats --no-streamConfirm the database starts before investigating Apache Fineract.
docker compose logs --tail=300 databaseLook for database, Liquibase, Java memory, tenant and startup failures.
docker compose logs --tail=500 fineractTest Apache Fineract locally before investigating Nginx or the Web App.
curl -vk \
https://127.0.0.1:8443/fineract-provider/actuator/healthValidate the configuration and inspect frontend and API proxy logs.
sudo nginx -t
sudo systemctl status nginx --no-pager
sudo tail -n 200 /var/log/nginx/error.logConfirm DNS, HTTP, HTTPS, certificates and reverse-proxy routing.
curl -I http://mifos.example.com/
curl -I https://mifos.example.com/
curl -I \
https://api-mifos.example.com/fineract-provider/actuator/healthUse browser developer tools to identify frontend, CORS, certificate and API errors.
Open browser developer tools
Review Console
Review Network
Reload the page
Inspect failed requestsQuick navigation
Troubleshooting category
The terminal reports docker: command not found or Docker Compose is unavailable.
docker --version
docker compose version
sudo systemctl status docker --no-pagerThe current user cannot access /var/run/docker.sock.
groups
ls -l /var/run/docker.sock
sudo usermod -aG docker $USERdocker compose ps displays Restarting or the container repeatedly exits.
docker compose ps
docker compose logs --tail=400 SERVICE_NAME
docker inspect SERVICE_NAME | \
grep -A20 -B5 -E "State|ExitCode|Error"Docker cannot bind port 80, 443, 8443 or another configured host port.
sudo ss -lntp
sudo lsof -i :8443
docker ps --format "table {{.Names}}\t{{.Ports}}"Troubleshooting category
Apache Fineract cannot connect to the configured database host or port.
docker compose ps
docker compose logs --tail=300 database
nc -vz DATABASE_HOST 3306The logs show authentication failure or access denied.
mysql \
-h DATABASE_HOST \
-u fineract_app \
-p
SHOW GRANTS FOR 'fineract_app'@'%';Apache Fineract stops during schema validation or database migration.
docker compose logs --tail=800 fineract | \
grep -i -A20 -B20 "liquibase\|changeset\|migration\|checksum"Liquibase reports that a previously executed changeset has changed.
git status
git rev-parse HEAD
git diff
SELECT ID, AUTHOR, FILENAME, MD5SUM
FROM DATABASECHANGELOG
ORDER BY DATEEXECUTED DESC;Writes fail, containers stop or the database reports no space left.
df -h
df -i
sudo du -xh /var/lib/docker | sort -h | tail -30
sudo du -xh /opt/mifos | sort -h | tail -30Troubleshooting category
The health URL times out, refuses the connection or returns an error.
docker compose ps
docker compose logs --tail=500 fineract
sudo ss -lntp | grep 8443 || true
curl -vk \
https://127.0.0.1:8443/fineract-provider/actuator/healthAPI responses report an invalid or missing tenant identifier.
curl -k \
-H "Fineract-Platform-TenantId: default" \
https://127.0.0.1:8443/fineract-provider/api/v1/officesThe backend responds but rejects authentication.
curl -k \
-u "USERNAME:PASSWORD" \
-H "Fineract-Platform-TenantId: default" \
-H "Accept: application/json" \
https://127.0.0.1:8443/fineract-provider/api/v1/officesAuthentication succeeds but the user lacks access to the requested operation.
Review user role in Mifos
Review permission mapping
Test using an administrator account only for diagnosisFineract crashes or logs Java heap-space errors.
free -h
docker stats --no-stream
docker inspect fineract | \
grep -A20 -B5 -E "Memory|Env"Troubleshooting category
The browser displays an empty page after deployment.
sudo find /var/www/mifos-web-app -maxdepth 2 -type f | \
sed -n '1,100p'
curl -s https://mifos.example.com/ | head -40The frontend loads but authentication requests fail.
curl -I \
https://api-mifos.example.com/fineract-provider/actuator/healthThe browser blocks API requests from the frontend domain.
curl -I \
-H "Origin: https://mifos.example.com" \
https://api-mifos.example.com/fineract-provider/actuator/healthNavigation works inside the app, but refreshing a nested route returns 404.
sudo nginx -T | \
grep -A20 -B10 "server_name mifos.example.com"The HTTPS frontend attempts to call an HTTP API.
grep -R "http://" -n /var/www/mifos-web-app | head -80Troubleshooting category
Nginx cannot connect to Apache Fineract.
curl -vk \
https://127.0.0.1:8443/fineract-provider/actuator/health
sudo tail -n 200 /var/log/nginx/error.logDNS resolves to an old or incorrect IP address.
dig +short mifos.example.com A
dig +short mifos.example.com AAAA
getent hosts mifos.example.comLet's Encrypt cannot reach the HTTP challenge.
sudo ufw status verbose
sudo nginx -t
curl -I http://mifos.example.com/The browser reports an expired certificate or hostname mismatch.
openssl s_client \
-connect mifos.example.com:443 \
-servername mifos.example.com \
</dev/null 2>/dev/null | \
openssl x509 -noout -subject -issuer -dates
sudo certbot certificates
sudo certbot renew --dry-runRequesting technical support
A complete and sanitised diagnostic bundle helps developers and support teams identify the problem quickly.
MifosX production support
MifosX provides Apache Fineract and Mifos diagnosis, installation recovery, database support, upgrade assistance, performance troubleshooting and production support.