Troubleshooting

Use these checks for common local-development failures.

Symptom	First checks
Backend modules cannot be imported	Confirm the backend command is running from the intended project directory and Python environment.
PostgreSQL connection is refused	Confirm PostgreSQL is running and the local database connection is configured correctly.
Alembic cannot import application modules	Run Alembic from the backend environment where project dependencies are installed.
Migration state is unexpected	Run `alembic heads` and `alembic current` before attempting an upgrade, downgrade, or stamp operation.
Dependency installation fails	Confirm the selected Python environment is active and reinstall from the tracked requirement files.
Tests fail after setup	Separate dependency, configuration, database, and application failures before changing runtime code.

Database safety

Never substitute a production database connection while troubleshooting a local setup.

Do not use alembic stamp, alembic downgrade, or destructive database commands merely to make a local check pass.

Review: