Installation Guide · Step 10

Troubleshoot Mifos X installation problems

Diagnose Docker, database, Liquibase, Apache Fineract, Mifos Web App, Nginx, domain, SSL, authentication and API connection problems using a structured troubleshooting process.

Structured diagnosis

Troubleshoot in the correct order

Start with infrastructure and dependencies. Do not investigate the frontend before confirming the database and Apache Fineract are healthy.

01

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 --failed
02

Check Docker services

Identify containers that are stopped, unhealthy or repeatedly restarting.

docker compose ps
docker ps -a
docker stats --no-stream
03

Inspect database logs

Confirm the database starts before investigating Apache Fineract.

docker compose logs --tail=300 database
04

Inspect Apache Fineract logs

Look for database, Liquibase, Java memory, tenant and startup failures.

docker compose logs --tail=500 fineract
05

Verify the backend directly

Test Apache Fineract locally before investigating Nginx or the Web App.

curl -vk \
  https://127.0.0.1:8443/fineract-provider/actuator/health
06

Verify Nginx

Validate 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.log
07

Test the public domains

Confirm 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/health
08

Inspect the browser

Use browser developer tools to identify frontend, CORS, certificate and API errors.

Open browser developer tools
Review Console
Review Network
Reload the page
Inspect failed requests

Troubleshooting category

Docker and container problems

Docker command not found

Symptoms

The terminal reports docker: command not found or Docker Compose is unavailable.

What to check

  • Confirm Docker Engine is installed
  • Confirm the Docker Compose plugin is installed
  • Restart the terminal session
Diagnostic commands
docker --version
docker compose version

sudo systemctl status docker --no-pager
Recommended resolution: Install Docker Engine and the Docker Compose plugin from a trusted repository, then enable and start the Docker service.

Permission denied accessing Docker

Symptoms

The current user cannot access /var/run/docker.sock.

What to check

  • Check current group membership
  • Check Docker socket ownership
  • Confirm the user was added to the docker group
Diagnostic commands
groups
ls -l /var/run/docker.sock

sudo usermod -aG docker $USER
Recommended resolution: Add the user to the Docker group and start a new login session. Avoid changing Docker socket permissions to insecure global access.

Container keeps restarting

Symptoms

docker compose ps displays Restarting or the container repeatedly exits.

What to check

  • Inspect recent logs
  • Check environment variables
  • Check database connectivity
  • Check memory and disk space
Diagnostic commands
docker compose ps
docker compose logs --tail=400 SERVICE_NAME

docker inspect SERVICE_NAME | \
  grep -A20 -B5 -E "State|ExitCode|Error"
Recommended resolution: Resolve the underlying application or dependency error rather than repeatedly restarting the container.

Port already in use

Symptoms

Docker cannot bind port 80, 443, 8443 or another configured host port.

What to check

  • Identify the process using the port
  • Review Docker port mappings
  • Check duplicate services
Diagnostic commands
sudo ss -lntp
sudo lsof -i :8443

docker ps --format "table {{.Names}}\t{{.Ports}}"
Recommended resolution: Stop the conflicting service or change the host-port mapping while keeping internal service communication consistent.

Troubleshooting category

Database and Liquibase problems

Database connection refused

Symptoms

Apache Fineract cannot connect to the configured database host or port.

What to check

  • Confirm the database service is running
  • Check hostname and port
  • Check Docker network membership
  • Check firewall rules
Diagnostic commands
docker compose ps
docker compose logs --tail=300 database

nc -vz DATABASE_HOST 3306
Recommended resolution: Correct the database hostname, port, network or service state. Inside Docker, use the Compose service name rather than localhost where appropriate.

Access denied for database user

Symptoms

The logs show authentication failure or access denied.

What to check

  • Verify username and password
  • Verify allowed host
  • Review database grants
  • Check secret-file formatting
Diagnostic commands
mysql \
  -h DATABASE_HOST \
  -u fineract_app \
  -p

SHOW GRANTS FOR 'fineract_app'@'%';
Recommended resolution: Correct the credentials or database grants. Avoid using the database root account for the application.

Liquibase migration failure

Symptoms

Apache Fineract stops during schema validation or database migration.

What to check

  • Preserve the database before making changes
  • Identify the failed changeset
  • Confirm the application version
  • Check manual schema modifications
Diagnostic commands
docker compose logs --tail=800 fineract | \
  grep -i -A20 -B20 "liquibase\|changeset\|migration\|checksum"
Recommended resolution: Reproduce the problem using a restored staging database. Do not delete Liquibase records or edit production schema history without a tested recovery plan.

Liquibase checksum mismatch

Symptoms

Liquibase reports that a previously executed changeset has changed.

What to check

  • Check whether migration files were modified
  • Compare deployed source commit
  • Review database change-log history
Diagnostic commands
git status
git rev-parse HEAD
git diff

SELECT ID, AUTHOR, FILENAME, MD5SUM
FROM DATABASECHANGELOG
ORDER BY DATEEXECUTED DESC;
Recommended resolution: Return to the correct source version or follow a reviewed migration-recovery procedure. Do not casually clear production checksums.

Database disk space exhausted

Symptoms

Writes fail, containers stop or the database reports no space left.

What to check

  • Check filesystem space
  • Check inode usage
  • Review database and backup sizes
  • Review logs and temporary files
Diagnostic commands
df -h
df -i
sudo du -xh /var/lib/docker | sort -h | tail -30
sudo du -xh /opt/mifos | sort -h | tail -30
Recommended resolution: Free space safely, expand storage and implement monitoring. Never delete database files manually.

Troubleshooting category

Apache Fineract backend problems

Fineract health endpoint does not respond

Symptoms

The health URL times out, refuses the connection or returns an error.

What to check

  • Confirm the container is running
  • Check exposed ports
  • Review startup logs
  • Confirm the configured protocol
Diagnostic commands
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/health
Recommended resolution: Resolve startup, port, TLS or database errors before connecting the frontend.

Tenant not found

Symptoms

API responses report an invalid or missing tenant identifier.

What to check

  • Check the request tenant header
  • Review tenant database configuration
  • Confirm the frontend tenant setting
Diagnostic commands
curl -k \
  -H "Fineract-Platform-TenantId: default" \
  https://127.0.0.1:8443/fineract-provider/api/v1/offices
Recommended resolution: Use a tenant identifier that exists in the platform configuration and ensure the tenant database is reachable.

HTTP 401 Unauthorized

Symptoms

The backend responds but rejects authentication.

What to check

  • Verify credentials
  • Verify authentication mode
  • Verify tenant header
  • Review user status
Diagnostic commands
curl -k \
  -u "USERNAME:PASSWORD" \
  -H "Fineract-Platform-TenantId: default" \
  -H "Accept: application/json" \
  https://127.0.0.1:8443/fineract-provider/api/v1/offices
Recommended resolution: Correct credentials, authentication configuration or tenant settings. Change any default credentials before production use.

HTTP 403 Forbidden

Symptoms

Authentication succeeds but the user lacks access to the requested operation.

What to check

  • Review the user's role
  • Review assigned permissions
  • Confirm office restrictions
Diagnostic commands
Review user role in Mifos
Review permission mapping
Test using an administrator account only for diagnosis
Recommended resolution: Grant only the specific permission needed. Do not solve permission issues by assigning every user administrator access.

Java OutOfMemoryError

Symptoms

Fineract crashes or logs Java heap-space errors.

What to check

  • Check host memory
  • Check container limits
  • Review JVM heap settings
  • Identify heavy reports or jobs
Diagnostic commands
free -h
docker stats --no-stream

docker inspect fineract | \
  grep -A20 -B5 -E "Memory|Env"
Recommended resolution: Adjust JVM and container memory only after identifying the workload causing the failure. Review reports, jobs and database performance.

Troubleshooting category

Mifos Web App problems

Web App shows a blank page

Symptoms

The browser displays an empty page after deployment.

What to check

  • Open browser developer tools
  • Check JavaScript errors
  • Verify asset paths
  • Verify index.html exists
Diagnostic commands
sudo find /var/www/mifos-web-app -maxdepth 2 -type f | \
  sed -n '1,100p'

curl -s https://mifos.example.com/ | head -40
Recommended resolution: Correct the deployment directory, base path, environment configuration or missing frontend assets.

Login page opens but login fails

Symptoms

The frontend loads but authentication requests fail.

What to check

  • Check the API URL
  • Check tenant identifier
  • Check browser Network tab
  • Test the backend directly
Diagnostic commands
curl -I \
  https://api-mifos.example.com/fineract-provider/actuator/health
Recommended resolution: Correct the frontend runtime configuration, backend URL, tenant or authentication settings.

CORS error

Symptoms

The browser blocks API requests from the frontend domain.

What to check

  • Check frontend and API origins
  • Review reverse-proxy routing
  • Review backend cross-origin configuration
Diagnostic commands
curl -I \
  -H "Origin: https://mifos.example.com" \
  https://api-mifos.example.com/fineract-provider/actuator/health
Recommended resolution: Configure an approved same-origin or cross-origin architecture. Do not disable browser security as a workaround.

404 after page refresh

Symptoms

Navigation works inside the app, but refreshing a nested route returns 404.

What to check

  • Review Nginx try_files
  • Confirm Angular route fallback
  • Check the configured web root
Diagnostic commands
sudo nginx -T | \
  grep -A20 -B10 "server_name mifos.example.com"
Recommended resolution: Configure Nginx to serve index.html when a requested frontend route is not a physical file.

Mixed-content error

Symptoms

The HTTPS frontend attempts to call an HTTP API.

What to check

  • Inspect frontend runtime configuration
  • Check browser Network requests
  • Confirm API uses HTTPS
Diagnostic commands
grep -R "http://" -n /var/www/mifos-web-app | head -80
Recommended resolution: Update the frontend to use the HTTPS API URL and rebuild or replace the runtime configuration.

Troubleshooting category

Nginx, domain and SSL problems

502 Bad Gateway

Symptoms

Nginx cannot connect to Apache Fineract.

What to check

  • Check Fineract health
  • Check proxy_pass address
  • Check container port mapping
  • Review Nginx error logs
Diagnostic commands
curl -vk \
  https://127.0.0.1:8443/fineract-provider/actuator/health

sudo tail -n 200 /var/log/nginx/error.log
Recommended resolution: Correct the upstream address or restore the backend service before reloading Nginx.

Domain does not point to the server

Symptoms

DNS resolves to an old or incorrect IP address.

What to check

  • Check A and AAAA records
  • Check local DNS resolution
  • Check proxy or CDN configuration
Diagnostic commands
dig +short mifos.example.com A
dig +short mifos.example.com AAAA

getent hosts mifos.example.com
Recommended resolution: Correct the DNS record and wait for propagation based on the configured TTL.

Certbot validation fails

Symptoms

Let's Encrypt cannot reach the HTTP challenge.

What to check

  • Confirm DNS resolution
  • Confirm port 80 is open
  • Check Nginx configuration
  • Check external proxy settings
Diagnostic commands
sudo ufw status verbose
sudo nginx -t

curl -I http://mifos.example.com/
Recommended resolution: Ensure the domain reaches the server on port 80 before requesting the certificate.

Expired or incorrect certificate

Symptoms

The browser reports an expired certificate or hostname mismatch.

What to check

  • Inspect certificate dates
  • Inspect certificate subject names
  • Check Certbot renewal status
Diagnostic commands
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-run
Recommended resolution: Renew or reissue the certificate with every required hostname and confirm Nginx uses the correct certificate files.

Requesting technical support

Prepare a useful diagnostic bundle

A complete and sanitised diagnostic bundle helps developers and support teams identify the problem quickly.

  • Exact Apache Fineract release or Git commit
  • Exact Mifos Web App Git commit
  • Operating-system version
  • Docker and Docker Compose versions
  • Database engine and version
  • Sanitised Docker Compose configuration
  • Container status output
  • Relevant application logs
  • Nginx configuration
  • Exact error message and time
  • Steps already attempted
  • Whether the error occurs in staging or production

MifosX production support

Unable to resolve a Mifos or Fineract installation issue?

MifosX provides Apache Fineract and Mifos diagnosis, installation recovery, database support, upgrade assistance, performance troubleshooting and production support.