Business-Management/changelog/2026-04-12_troubleshooting.md

2026-04-12 — Troubleshoot dev stack startup

Timestamp: 2026-04-12T15:30:00

Summary

Fixed three startup failures discovered when running the dev stack for the first time.

Issues Fixed

1. ModuleNotFoundError: No module named 'app' — python scripts/seed.py does not add the working directory to sys.path. Changed to python -m scripts.seed which uses module mode and adds /app to the path. Added backend/scripts/__init__.py to make the directory a package.

2. relation "users" does not exist — No Alembic migration files existed, so alembic upgrade head was a no-op. Generated the initial migration (38efeff7c45a_create_users_table.py) by running alembic revision --autogenerate inside the backend container against the live database.

3. ValueError: password cannot be longer than 72 bytes (passlib + bcrypt 4.x incompatibility) — passlib is unmaintained and its bcrypt wrap-bug detection raises an exception against bcrypt 4.x. Replaced passlib[bcrypt] with direct bcrypt>=4.0 usage in both pyproject.toml and app/core/security.py.

Smoke Test Results (all passing)

• GET /api/health → {"status":"ok"}
• POST /api/auth/login → JWT token issued for test@example.com
• GET /api/users/me → returns user profile with valid token
• POST /api/auth/register → new user created successfully
• Weak password ("password") → rejected with detailed validation errors
• Frontend http://localhost:5173 → HTTP 200

Files Added

• backend/scripts/__init__.py — makes scripts/ a Python package
• backend/alembic/versions/38efeff7c45a_create_users_table.py — initial migration

Files Modified

• backend/scripts/start_dev.sh — python scripts/seed.py → python -m scripts.seed
• backend/pyproject.toml — passlib[bcrypt]>=1.7 → bcrypt>=4.0
• backend/app/core/security.py — replaced passlib with direct bcrypt calls