besser-troubleshooting

BESSER Troubleshooting

Quick reference for diagnosing and fixing common issues. Organized by symptom. This is an intentionally flat, single-file skill — a fast lookup you scan top-to-bottom or search, with no references/ subdirectory.

---

Installation Issues

pip install besser fails with native dependency errors

Several BESSER dependencies require system libraries:

Dependency	Requires	Fix (Ubuntu/Debian)	Fix (macOS)
psycopg2-binary	PostgreSQL client libs	apt install libpq-dev	brew install postgresql
pyodbc	ODBC driver manager	apt install unixodbc-dev	brew install unixodbc
oracledb	Oracle Instant Client	Download from Oracle	Download from Oracle

If you don't need a specific database, these won't block core BESSER functionality — most generators work fine with SQLite (no native deps needed).

pip install -e . fails or installs nothing

• Must be run from the repository root (where setup.cfg and pyproject.toml live; setup.cfg holds the package metadata and python_requires).
• Requires setuptools>=42 and wheel. Upgrade first: pip install --upgrade setuptools wheel.
• Check you're in the right virtual environment: which python (Unix) or where python (Windows).

Python version incompatibility

BESSER requires Python 3.11+ (enforced by python_requires = >=3.11 in setup.cfg). Check with:

python --version

If you're on 3.10 or earlier, upgrade Python or use pyenv/conda to manage versions.

Windows-specific: venv\Scripts\activate not found

The activation path is venv\Scripts\activate (capital S). A common mistake in some docs is venv\Script\activate (missing the 's') — this will fail.

:: Correct:
venv\Scripts\activate

---

Import Errors

ModuleNotFoundError: No module named 'besser'

1. Not installed: Run pip install -e . from the repo root, or pip install besser.
2. Wrong environment: Activate your venv first (source venv/bin/activate or venv\Scripts\activate).
3. Multiple Python installs: pip and python may point to different installations. Use python -m pip install -e . to ensure alignment.