Installation Issues

This guide covers common issues that may arise during the installation and setup of the Zyeta backend development environment.

Python Environment Issues

Poetry Installation Failures

Poetry installation fails

Symptoms:

Error messages during Poetry installation
command not found: poetry after installation

Solutions:

Ensure Python is correctly installed:

python --version  # Should be 3.10 or higher

Try the alternative installation method:

# Using pip
pip install poetry

# Or using the official installer with different parameters
curl -sSL https://install.python-poetry.org | POETRY_HOME=$HOME/.poetry python3 -

Add Poetry to your PATH:

# For Bash/Zsh
export PATH="$HOME/.poetry/bin:$PATH"

# For Windows PowerShell
$Env:Path += ";$Env:USERPROFILE\.poetry\bin"

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

Solutions:

Update Poetry to the latest version:
```
poetry self update
```

Clear Poetry’s cache:

poetry cache clear .
poetry cache clear --all pypi

Try installing with verbose output for more information:
```
poetry install -v
```
As a last resort, delete poetry.lock and create a fresh one:
```
rm poetry.lock
poetry install
```
Only do this in a development environment, as it may change your dependency versions.

Poetry can't find Python interpreter

Symptoms:

Error like: Poetry could not find a Python executable

Solutions:

Explicitly set Python version for your project:
```
poetry env use python3.10
```
Verify that the correct Python version is installed and available:
```
which python3.10
python3.10 --version
```
If using pyenv, ensure it’s properly initialized:
```
eval "$(pyenv init --path)"
pyenv local 3.10.x
```

Virtual Environment Problems

Virtual environment activation issues

Symptoms:

command not found: activate or similar errors
Virtual environment does not activate correctly

Solutions:

Verify your shell and use the correct activation command:

Bash/Zsh (Linux/macOS):
```
source venv/bin/activate
```
Windows Command Prompt:
```
venv\Scripts\activate.bat
```
Windows PowerShell:
```
.\venv\Scripts\Activate.ps1
```

If PowerShell has execution policy issues:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Recreate the virtual environment if necessary:
```
rm -rf venv
python -m venv venv
```

Import errors after installation

Symptoms:

ModuleNotFoundError: No module named 'X' despite successful installation

Solutions:

Verify the package is installed:

pip list | grep package-name
# or with Poetry
poetry show

Ensure you’re using the correct Python environment:

which python  # Should point to your virtual environment

Try reinstalling the specific package:

pip install -e .  # If installing the project itself
# or
pip install package-name

Check for Python path issues:

python -c "import sys; print(sys.path)"  # Should include your project path

PostgreSQL Issues

PostgreSQL installation problems

Symptoms:

Unable to install PostgreSQL
PostgreSQL service won’t start

Solutions:

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:

# Using Homebrew
brew install postgresql@14
brew services start postgresql@14

For Linux users:

# Ubuntu/Debian
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

As an alternative, use Docker:

docker run --name postgres -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 -d postgres:14

PostgreSQL connection issues

Symptoms:

could not connect to server: Connection refused
psql: error: FATAL: role "postgres" does not exist

Solutions:

Verify PostgreSQL is running:

# Check service status
sudo systemctl status postgresql  # Linux
brew services list  # macOS

# Check if you can connect with psql
psql -U postgres

Create the missing user if needed:

sudo -u postgres createuser --superuser your_username

Check and update PostgreSQL authentication settings:
- Edit pg_hba.conf (location varies by system)
- Change authentication method from peer to md5 or trust for local connections (for development only)

For Docker, check container status:

docker ps  # Should show running postgres container
docker logs postgres  # Check container logs for errors

pgvector extension installation issues

Symptoms:

ERROR: could not open extension control file "pgvector"
Migration fails with pgvector-related errors

Solutions:

Install the pgvector extension:

# For local PostgreSQL installation
sudo apt-get install postgresql-14-pgvector  # Linux
brew install pgvector  # macOS

For Docker, use a container with pgvector pre-installed:

# Use the pgvector-enabled image
docker pull ankane/pgvector
docker run --name postgres -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 -d ankane/pgvector

Create the extension in your database:
```
CREATE EXTENSION IF NOT EXISTS vector;
```
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

Symptoms:

pre-commit: command not found
Pre-commit hooks don’t run when committing

Solutions:

Install pre-commit globally:
```
pip install pre-commit
```
Install the git hooks:
```
pre-commit install
```
Update to the latest hooks:
```
pre-commit autoupdate
```
Run the hooks manually to verify they work:
```
pre-commit run --all-files
```

Pre-commit hooks failing

Symptoms:

Commit blocked with error messages from ruff, mypy, or other checks
Hooks taking too long to run

Solutions:

Fix the specific issues reported by the checks:
- For ruff issues: ruff check --fix
- For mypy issues: Fix type annotations according to errors

If hooks are too slow, run selectively:

pre-commit run ruff --files path/to/changed/files.py

Temporarily skip hooks if needed (not recommended for regular use):
```
git commit --no-verify -m "Commit message"
```
Check configuration files for issues:
- .pre-commit-config.yaml - Hook settings
- ruff.toml - Ruff linter configuration
- mypy.ini - MyPy configuration

Docker Issues

Docker installation problems

Symptoms:

Unable to install Docker
Docker commands not found

Solutions:

Follow the official installation guides:
For Windows, ensure WSL2 is installed and configured:
```
wsl --install
```

Verify installation:

docker --version
docker run hello-world

Docker Compose issues

Symptoms:

docker-compose: command not found
Issues with compose.yml configuration

Solutions:

Install Docker Compose:

# Modern Docker installations include Compose functionality
docker compose version

# If using older Docker, install separately
pip install docker-compose

Verify your compose.yml:

docker compose config  # Validates and prints compose configuration

Common formatting issues:
- Indentation errors in YAML
- Missing quotes around values with special characters
- Environment variables not properly set

Docker build failures

Symptoms:

docker compose up --build fails with errors
Issues with the Dockerfile

Solutions:

Check Dockerfile for errors:
- Verify paths and commands
- Ensure base image exists

Check for network issues:

docker network ls
docker network create nginx_proxy_manager_default  # Create missing network

Build with verbose output for more information:

docker compose build --progress=plain zyeta.backend

Clean up Docker environment:

docker system prune -a  # Warning: Removes all unused images

Configuration Issues

Environment file (.env) problems

Symptoms:

Application fails to start with configuration errors
Missing environment variables

Solutions:

Ensure .env file exists and has correct format:
```
cp .env.local .env  # Create from template
```
Check for common formatting issues:
- No spaces around equals sign: KEY=value (correct) vs KEY = value (incorrect)
- No quotes around values unless needed for escaping
- Line endings (Windows vs Unix)
Verify all required variables are set:
- Check settings.py for required variables
- Compare with .env.local template

Test environment loading:

# In Python interpreter
from dotenv import load_dotenv
load_dotenv()
import os
print(os.environ.get("DATABASE_URL"))  # Should print your configured value

Alembic configuration issues

Symptoms:

Migration commands fail
alembic.ini not found or incorrect

Solutions:

Create alembic.ini from template:
```
cp alembic.copy.ini alembic.ini
```
Update the database URL:
- Edit sqlalchemy.url in alembic.ini
- Remember to escape % characters as %%

Check alembic directory structure:

ls -la alembic
# Should include env.py, script.py.mako, and versions/

Recreate alembic setup if necessary:

alembic init alembic
# Then manually update alembic/env.py with your models import

System-Specific Issues

Windows-Specific Issues

Windows path length limitations

Symptoms:

Errors about path too long
Files not found in deeply nested directories

Solutions:

Enable long paths in Windows:

# Run as administrator
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Use shorter paths for your project:
- Install in C:\Dev instead of deeply nested directories
- Use shorter folder names

Enable Git long paths:

git config --system core.longpaths true

Windows line ending issues

Symptoms:

Git shows files as changed when you didn’t modify them
Scripts fail with syntax errors

Solutions:

Configure Git to handle line endings correctly:

git config --global core.autocrlf true  # For Windows

Add a .gitattributes file to your project:

# .gitattributes
* text=auto
*.py text eol=lf
*.sh text eol=lf

Fix existing files:

# Convert all files to LF
dos2unix path/to/file.py

# Or use VSCode: Open file > Bottom right corner > CRLF > Change to LF

macOS-Specific Issues

macOS file permission issues

Symptoms:

Permission denied errors when running scripts
Unable to write to directories

Solutions:

Fix script permissions:
```
chmod +x path/to/script.sh
```

Check folder ownership:

ls -la
sudo chown -R $(whoami) /path/to/directory

For Homebrew issues:

sudo chown -R $(whoami) /usr/local/Cellar /usr/local/Homebrew

macOS Gatekeeper blocking applications

Symptoms:

“App cannot be opened because the developer cannot be verified”

Solutions:

Open application while bypassing Gatekeeper:
- Right-click the app > Open
- When prompted, click “Open” again

For command-line tools:

xattr -d com.apple.quarantine /path/to/executable

Linux-Specific Issues

Linux dependency issues

Symptoms:

Missing shared libraries
Build failures for native extensions

Solutions:

Ubuntu/Debian: Install development packages:

sudo apt update
sudo apt install build-essential python3-dev libpq-dev

CentOS/RHEL/Fedora:

sudo dnf groupinstall "Development Tools"
sudo dnf install python3-devel postgresql-devel

For specific package errors, install the required libraries:
- SQLAlchemy with PostgreSQL: sudo apt install libpq-dev
- Cryptography: sudo apt install libssl-dev libffi-dev

Next Steps

If you’ve resolved your installation issues, proceed to:

If you’re still experiencing problems, check the other troubleshooting guides or contact the development team for assistance.

Introduction

Getting Started

Architecture

Authentication

API Reference

Development Guides

Troubleshooting

Installation Issues

Python Environment Issues

Poetry Installation Failures

Virtual Environment Problems

PostgreSQL Issues

Pre-commit Hook Issues

Docker Issues

Configuration Issues

System-Specific Issues

Windows-Specific Issues

macOS-Specific Issues

Linux-Specific Issues

Next Steps

Introduction

Getting Started

Architecture

Authentication

API Reference

Development Guides

Troubleshooting

​Python Environment Issues

​Poetry Installation Failures

​Virtual Environment Problems

​PostgreSQL Issues

​Pre-commit Hook Issues

​Docker Issues

​Configuration Issues

​System-Specific Issues

​Windows-Specific Issues

​macOS-Specific Issues

​Linux-Specific Issues

​Next Steps

Python Environment Issues

Poetry Installation Failures

Virtual Environment Problems

PostgreSQL Issues

Pre-commit Hook Issues

Docker Issues

Configuration Issues

System-Specific Issues

Windows-Specific Issues

macOS-Specific Issues

Linux-Specific Issues

Next Steps