Skip to main content

Troubleshooting

Common issues and solutions for self-hosted BillManager installations.

Container Won't Start​

Check Logs​

docker-compose logs billmanager

Common Errors​

"JWT_SECRET_KEY or FLASK_SECRET_KEY must be set in production"​

You need to set at least one secret key:

environment:
  - FLASK_SECRET_KEY=your-generated-secret-here

Generate with:

openssl rand -hex 32

Database Connection Errors​

Check the database container:

docker-compose logs db

Verify your DATABASE_URL is correct:

postgresql://USERNAME:PASSWORD@HOST:PORT/DATABASE

Lost Admin Password​

Option 1: Reset via Database​

Connect to the database:

docker exec -it billmanager-db-1 psql -U billsuser billmanager

Set the user to require password change on next login:

UPDATE users
SET password_change_required = true,
    change_token = 'temp-reset-token'
WHERE username = 'admin';

Then use the forgot password flow or contact support.

Option 2: Fresh Start (Development Only)​

Data Loss Warning

This deletes ALL data. Only use for development or fresh installations.

docker-compose down -v
docker-compose up -d
docker-compose logs billmanager | grep -A 5 "INITIAL ADMIN CREDENTIALS"

A new random password will be generated.

Email Issues​

"Invite User" Button Not Visible​

Email is not configured. Add these environment variables:

environment:
  - RESEND_API_KEY=re_your_api_key
  - [email protected]
  - APP_URL=https://your-billmanager-url.com

Restart the container after adding them.

Emails Not Received​

  1. Check Resend Dashboard - View delivery status at resend.com
  2. Verify FROM_EMAIL - Must match a verified domain in Resend
  3. Check Spam Folders - Emails may be filtered
  4. Verify APP_URL - Links in emails use this URL

Invalid API Key​

  • Ensure the key starts with re_
  • Check for extra whitespace
  • Verify it hasn't been revoked in Resend dashboard

Performance Issues​

Slow Response Times​

  1. Check available memory:

    docker stats billmanager

  2. Check database size:

    docker exec billmanager-db-1 psql -U billsuser billmanager -c "SELECT pg_size_pretty(pg_database_size('billmanager'));"

  3. Consider increasing container resources in docker-compose.yml

High Memory Usage​

Add memory limits:

services:
  billmanager:
    deploy:
      resources:
        limits:
          memory: 512M

Database Issues​

Check Database Health​

docker-compose exec db pg_isready -U billsuser

View Database Size​

docker exec billmanager-db-1 psql -U billsuser billmanager -c "\dt+"

Reset Database (Development Only)​

Data Loss Warning

This permanently deletes all data.

docker-compose down -v
docker-compose up -d

Getting Help​

If you can't resolve an issue:

  1. Search existing issues on GitHub
  2. Open a new issue with:
    • BillManager version (docker-compose logs billmanager | head -20)
    • Docker and Docker Compose versions
    • Relevant error messages from logs
    • Steps to reproduce the issue