Troubleshooting common installation and setup problems for the Definable backend
Poetry installation fails
command not found: poetry
after installationDependency conflicts with Poetry
SolverProblemError: Unable to find a suitable version for package X
poetry.lock
and create a fresh one:
Poetry can't find Python interpreter
Poetry could not find a Python executable
Virtual environment activation issues
command not found: activate
or similar errorsImport errors after installation
ModuleNotFoundError: No module named 'X'
despite successful installationPostgreSQL installation problems
Services.msc
> Find PostgreSQL service > StartPostgreSQL connection issues
could not connect to server: Connection refused
psql: error: FATAL: role "postgres" does not exist
pg_hba.conf
(location varies by system)peer
to md5
or trust
for local connections (for development only)pgvector extension installation issues
ERROR: could not open extension control file "pgvector"
vector
extensionPre-commit hook installation failures
pre-commit: command not found
Pre-commit hooks failing
ruff check --fix
.pre-commit-config.yaml
- Hook settingsruff.toml
- Ruff linter configurationmypy.ini
- MyPy configurationDocker installation problems
Docker Compose issues
docker-compose: command not found
compose.yml
configurationDocker build failures
docker compose up --build
fails with errorsEnvironment file (.env) problems
KEY=value
(correct) vs KEY = value
(incorrect)Alembic configuration issues
alembic.ini
not found or incorrectsqlalchemy.url
in alembic.iniWindows path length limitations
Windows line ending issues
macOS file permission issues
macOS Gatekeeper blocking applications
Linux dependency issues
sudo apt install libpq-dev
sudo apt install libssl-dev libffi-dev