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)​

:::danger 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. For SMTP, add provider, host, sender, and app URL settings:

environment:
  - EMAIL_PROVIDER=smtp
  - SMTP_HOST=smtp.example.com
  - SMTP_PORT=587
  - SMTP_USERNAME=your-smtp-username
  - SMTP_PASSWORD=your-smtp-password
  - SMTP_USE_TLS=true
  - [email protected]
  - APP_URL=https://your-billmanager-url.com

Restart the container after adding them.

Emails Not Received​

  1. Check Logs - docker-compose logs billmanager should show SMTP or Resend errors.
  2. Verify FROM_EMAIL - Must be allowed by your SMTP provider or verified Resend domain.
  3. Check Spam Folders - Emails may be filtered.
  4. Verify APP_URL - Links in emails use this URL.
  5. Check Provider Settings - STARTTLS usually uses port 587; implicit SSL usually uses 465.

SMTP Authentication Fails​

  • Confirm SMTP_USERNAME and SMTP_PASSWORD are both set and correct.
  • For Gmail, use an app password.
  • Confirm whether your provider requires SMTP_USE_TLS=true or SMTP_USE_SSL=true.
  • Check whether the provider rejects the configured FROM_EMAIL.

Invalid Resend 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)​

:::danger Data Loss Warning This permanently deletes all data. :::

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

Social Login Issues​

Login Buttons Not Appearing​

  • The provider is not enabled. Set OAUTH_GOOGLE_ENABLED=true (or the relevant provider) and restart the container.
  • Required credentials are missing. Check container logs for OAuth provider warnings.

"Provider not enabled" Error After Clicking Login Button​

  • The environment variables are set but the container hasn't been restarted since adding them.
  • Restart the container: docker-compose restart billmanager

"Failed to fetch provider configuration" Error​

  • BillManager couldn't reach the provider's discovery endpoint.
  • Check that the container has internet access.
  • For Apple/Google, verify the provider credentials are correct and the container can reach the provider.

Redirect URI Mismatch Error (from the provider)​

The callback URL registered with the provider doesn't match what BillManager is sending.

  • The correct callback URL is: {APP_URL}/auth/callback
  • Check that APP_URL is set correctly (including https://)
  • Ensure the redirect URI in the provider's configuration matches exactly

Social Login Creates New Account Instead of Linking​

  • The user's provider email doesn't match their BillManager email.
  • If the user already has an account, they should log in with their password first, then link the social account from Settings → Linked Accounts.
  • The user signed up via social login and has no password set.
  • They must set a password first before unlinking their social account.

Two-Factor Authentication Issues​

2FA Option Not Visible​

  • 2FA is not enabled. Set ENABLE_2FA=true and restart the container.

Verification Codes Not Arriving​

  • Check that email is configured (see Email Setup).
  • Verify the user has a valid email address on their account.
  • Check BillManager logs and your SMTP/Resend provider for delivery status.

Passkey Registration Fails Silently​

  • WEBAUTHN_RP_ID must match the domain in the browser's address bar exactly (no scheme, no port).
  • WEBAUTHN_ORIGIN must match the full origin including scheme (e.g., https://bills.yourdomain.com).
  • WebAuthn requires HTTPS in production. It only works over HTTP on localhost.

"2FA session expired" Error​

  • The 2FA challenge has a 5-minute time limit. If the user takes too long to enter their code, they need to start the login process again.

Locked Out of Account (Lost 2FA Access)​

If a user has lost access to their email and recovery codes:

  1. An admin can disable 2FA directly in the database: 
    docker exec -it billmanager-db-1 psql -U billsuser billmanager
    UPDATE twofa_config SET is_enabled = false WHERE user_id = (
      SELECT id FROM users WHERE username = 'the-username'
    );
  2. The user can then log in normally and re-enable 2FA from Settings.

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