Python Environment Issues
Poetry Installation Failures
Poetry installation fails
Poetry installation fails
Symptoms:
- Error messages during Poetry installation
command not found: poetry
after installation
-
Ensure Python is correctly installed:
-
Try the alternative installation method:
-
Add Poetry to your PATH:
Dependency conflicts with Poetry
Dependency conflicts with Poetry
Symptoms:
- Error messages like:
SolverProblemError: Unable to find a suitable version for package X
- Dependency resolution hangs for a long time
-
Update Poetry to the latest version:
-
Clear Poetryโs cache:
-
Try installing with verbose output for more information:
-
As a last resort, delete
poetry.lock
and create a fresh one:Only do this in a development environment, as it may change your dependency versions.
Poetry can't find Python interpreter
Poetry can't find Python interpreter
Symptoms:
- Error like:
Poetry could not find a Python executable
-
Explicitly set Python version for your project:
-
Verify that the correct Python version is installed and available:
-
If using pyenv, ensure itโs properly initialized:
Virtual Environment Problems
Virtual environment activation issues
Virtual environment activation issues
Symptoms:
command not found: activate
or similar errors- Virtual environment does not activate correctly
-
Verify your shell and use the correct activation command:
Bash/Zsh (Linux/macOS):
Windows Command Prompt:Windows PowerShell:
-
If PowerShell has execution policy issues:
-
Recreate the virtual environment if necessary:
Import errors after installation
Import errors after installation
Symptoms:
ModuleNotFoundError: No module named 'X'
despite successful installation
-
Verify the package is installed:
-
Ensure youโre using the correct Python environment:
-
Try reinstalling the specific package:
-
Check for Python path issues:
PostgreSQL Issues
PostgreSQL installation problems
PostgreSQL installation problems
Symptoms:
- Unable to install PostgreSQL
- PostgreSQL service wonโt start
-
For Windows users:
- Use the official PostgreSQL installer from postgresql.org
- Ensure the service is running:
Services.msc
> Find PostgreSQL service > Start
-
For macOS users:
-
For Linux users:
-
As an alternative, use Docker:
PostgreSQL connection issues
PostgreSQL connection issues
Symptoms:
could not connect to server: Connection refused
psql: error: FATAL: role "postgres" does not exist
-
Verify PostgreSQL is running:
-
Create the missing user if needed:
-
Check and update PostgreSQL authentication settings:
- Edit
pg_hba.conf
(location varies by system) - Change authentication method from
peer
tomd5
ortrust
for local connections (for development only)
- Edit
-
For Docker, check container status:
pgvector extension installation issues
pgvector extension installation issues
Symptoms:
ERROR: could not open extension control file "pgvector"
- Migration fails with pgvector-related errors
-
Install the pgvector extension:
-
For Docker, use a container with pgvector pre-installed:
-
Create the extension in your database:
-
If using Supabase, enable the extension through the dashboard:
- Go to Supabase dashboard > Database > Extensions
- Find and enable the
vector
extension
Pre-commit Hook Issues
Pre-commit hook installation failures
Pre-commit hook installation failures
Symptoms:
pre-commit: command not found
- Pre-commit hooks donโt run when committing
-
Install pre-commit globally:
-
Install the git hooks:
-
Update to the latest hooks:
-
Run the hooks manually to verify they work:
Pre-commit hooks failing
Pre-commit hooks failing
Symptoms:
- Commit blocked with error messages from ruff, mypy, or other checks
- Hooks taking too long to run
-
Fix the specific issues reported by the checks:
- For ruff issues:
ruff check --fix
- For mypy issues: Fix type annotations according to errors
- For ruff issues:
-
If hooks are too slow, run selectively:
-
Temporarily skip hooks if needed (not recommended for regular use):
-
Check configuration files for issues:
.pre-commit-config.yaml
- Hook settingsruff.toml
- Ruff linter configurationmypy.ini
- MyPy configuration
Docker Issues
Docker installation problems
Docker installation problems
Symptoms:
- Unable to install Docker
- Docker commands not found
- Follow the official installation guides:
-
For Windows, ensure WSL2 is installed and configured:
-
Verify installation:
Docker Compose issues
Docker Compose issues
Symptoms:
docker-compose: command not found
- Issues with
compose.yml
configuration
-
Install Docker Compose:
-
Verify your compose.yml:
-
Common formatting issues:
- Indentation errors in YAML
- Missing quotes around values with special characters
- Environment variables not properly set
Docker build failures
Docker build failures
Symptoms:
docker compose up --build
fails with errors- Issues with the Dockerfile
-
Check Dockerfile for errors:
- Verify paths and commands
- Ensure base image exists
-
Check for network issues:
-
Build with verbose output for more information:
-
Clean up Docker environment:
Configuration Issues
Environment file (.env) problems
Environment file (.env) problems
Symptoms:
- Application fails to start with configuration errors
- Missing environment variables
-
Ensure .env file exists and has correct format:
-
Check for common formatting issues:
- No spaces around equals sign:
KEY=value
(correct) vsKEY = value
(incorrect) - No quotes around values unless needed for escaping
- Line endings (Windows vs Unix)
- No spaces around equals sign:
-
Verify all required variables are set:
- Check settings.py for required variables
- Compare with .env.local template
-
Test environment loading:
Alembic configuration issues
Alembic configuration issues
Symptoms:
- Migration commands fail
alembic.ini
not found or incorrect
-
Create alembic.ini from template:
-
Update the database URL:
- Edit
sqlalchemy.url
in alembic.ini - Remember to escape % characters as %%
- Edit
-
Check alembic directory structure:
-
Recreate alembic setup if necessary:
System-Specific Issues
Windows-Specific Issues
Windows path length limitations
Windows path length limitations
Symptoms:
- Errors about path too long
- Files not found in deeply nested directories
-
Enable long paths in Windows:
-
Use shorter paths for your project:
- Install in C:\Dev instead of deeply nested directories
- Use shorter folder names
-
Enable Git long paths:
Windows line ending issues
Windows line ending issues
Symptoms:
- Git shows files as changed when you didnโt modify them
- Scripts fail with syntax errors
-
Configure Git to handle line endings correctly:
-
Add a .gitattributes file to your project:
-
Fix existing files:
macOS-Specific Issues
macOS file permission issues
macOS file permission issues
Symptoms:
- Permission denied errors when running scripts
- Unable to write to directories
-
Fix script permissions:
-
Check folder ownership:
-
For Homebrew issues:
macOS Gatekeeper blocking applications
macOS Gatekeeper blocking applications
Symptoms:
- โApp cannot be opened because the developer cannot be verifiedโ
- Open application while bypassing Gatekeeper:
- Right-click the app > Open
- When prompted, click โOpenโ again
- For command-line tools:
Linux-Specific Issues
Linux dependency issues
Linux dependency issues
Symptoms:
- Missing shared libraries
- Build failures for native extensions
-
Ubuntu/Debian: Install development packages:
-
CentOS/RHEL/Fedora:
-
For specific package errors, install the required libraries:
- SQLAlchemy with PostgreSQL:
sudo apt install libpq-dev
- Cryptography:
sudo apt install libssl-dev libffi-dev
- SQLAlchemy with PostgreSQL: