Troubleshooting Guide

This guide helps you resolve common issues when using WhoDB. Follow the step-by-step solutions to diagnose and fix problems.

Connection Issues

First: verify the database is reachable

Before adjusting anything in WhoDB, confirm the database is reachable from the machine (or container) WhoDB runs on:

# Basic reachability
nc -zv hostname 5432

# Full credential check with the native client
psql -h hostname -U username -d database    # PostgreSQL
mysql -h hostname -u username -p            # MySQL
mongosh --host hostname:27017 -u username -p # MongoDB

If the native client can't connect either, the problem is network reachability, database health, firewall rules, or credentials — fix that first. If the native client works but WhoDB doesn't, continue below.

Session and Login State Issues

Docker Networking

Performance Issues

UI and Usability Issues

Finding Logs

When diagnosing server-side problems, WhoDB's logs are the first place to look:

• By default, logs go to the container/process stdout: docker logs whodb
• WHODB_LOG_LEVEL sets verbosity (debug, info, warn, error, none)
• WHODB_LOG_FORMAT=json switches to JSON logs for log collectors
• WHODB_LOG_FILE redirects application logs to a file (default means /var/log/whodb/whodb.log)
• WHODB_ACCESS_LOG_FILE redirects HTTP access logs to a file (default means /var/log/whodb/whodb.access.log)

See Installation for the full environment variable reference and Monitoring Integration for log shipping examples.

Helpful Resources