besser-troubleshooting

name	besser-troubleshooting
description	Diagnose and fix BESSER errors fast. Use this skill whenever the user is staring at a Python traceback, ImportError, ModuleNotFoundError, ValueError, TypeError, AttributeError, jinja2.TemplateNotFound, subprocess.CalledProcessError, or any other failure originating from BESSER (besser.BUML, besser.generators, besser.utilities). Covers installation failures (`pip install besser` errors, native dependency build failures for psycopg2/pyodbc/oracledb, Python version mismatches, Windows venv path quirks), import errors (`String` vs `StringType`, missing `bocl==1.0.1`, `antlr4-python3-runtime` version mismatch), model construction errors (spaces or hyphens in names, duplicate enum literals, invalid multiplicities, generalization-to-self, more than one is_id per class), generator crashes (Invalid DBMS, Django subprocess failures, missing GUIModel for WebApp, silent SQLGenerator failures, invalid Qiskit backend), Docker and deployment problems (port conflicts, docker-compose vs docker compose, missing system libs in slim images), OCL constraint parse failures, and model-to-output drift (changes not appearing in regenerated code). Trigger on any error message that mentions `besser` in the traceback, even if the user does not explicitly ask for troubleshooting. Provides a minimal-reproduction template and quick diagnostic commands; defer to besser-generators for non-error questions about specific generator behavior.
license	Apache-2.0
compatibility	["claude-code","cursor","cline","windsurf","copilot"]
metadata	{"author":"BESSER-PEARL","version":"0.3.0","repository":"https://github.com/BESSER-PEARL/BESSER-Skills"}

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.

ImportError: cannot import name 'X' from 'besser.BUML.metamodel.structural'

Check the exact name. Common mistakes:

Wrong	Correct
String	StringType
Integer	IntegerType
Float	FloatType
Boolean	BooleanType
Date	DateType
DateTime	DateTimeType
Association	BinaryAssociation (for 2-end associations)

The primitive types are singleton instances, not classes. You import them directly: from besser.BUML.metamodel.structural import StringType.

ImportError related to bocl

The OCL constraint checker requires bocl==1.0.1 (exact version). If you installed a different version or it's missing:

pip install bocl==1.0.1

This only affects OCL validation — generators work without it.

ImportError related to antlr4

The PlantUML parser requires antlr4-python3-runtime>=4.13.1. The runtime version must be compatible with the grammar files shipped with BESSER. Install:

pip install antlr4-python3-runtime>=4.13.1

If you get runtime parse errors after upgrading, the ANTLR runtime version may be too new for the shipped grammar. Pin to 4.13.1 or 4.13.2.

plantuml_to_buml() parses but the model is empty or wrong

The converter only handles a subset of PlantUML class-diagram syntax. If a .plantuml file converts without error but yields missing classes, associations, or attributes, the input likely used unsupported notation (n-ary associations, non-class diagrams, stereotypes/OCL) rather than a BESSER bug. See the besser-user skill's references/plantuml.md for the exact supported subset, then adjust the diagram or add the missing pieces in Python after conversion.

ImportError for optional packages

These packages are only needed for specific features:

Package	Needed for	Install
deep_translator	Agent personalization (translation)	pip install deep-translator
docker	Docker image building in BackendGenerator	pip install docker
qiskit	Running generated quantum circuits	pip install qiskit
torch / tensorflow	Running generated NN code	pip install torch / pip install tensorflow

---

Model Construction Errors

ValueError: 'My Name' is invalid. Name cannot contain spaces.

All B-UML names (classes, attributes, associations, etc.) must not contain spaces. Use underscores: My_Name.

ValueError: 'my-name' is invalid. Hyphens are not allowed; use '_' instead.

Replace hyphens with underscores: my_name.

ValueError: Invalid primitive data type

Valid primitive type names for PrimitiveDataType(name): int, float, str, bool, time, date, datetime, timedelta, any.

More commonly, use the pre-built singletons: StringType, IntegerType, etc.

ValueError: A class cannot have more than one attribute marked as 'id'

Only one Property per class can have is_id=True. Pick one primary key attribute.

ValueError: A binary association must have exactly two ends

BinaryAssociation requires a set of exactly 2 Property objects as ends. Check that you're passing ends={end1, end2} with both ends.

ValueError: A class cannot be a generalization of itself

Generalization(general=A, specific=A) is not allowed. Check that general and specific are different classes.

ValueError: The model cannot have types with duplicate names

Two types in your DomainModel share the same name. Each class, enumeration, and data type must have a unique name within the model.

ValueError: Invalid min/max multiplicity

• min_multiplicity must be >= 0.
• max_multiplicity must be > 0 and >= min.
• Use "*" or UNLIMITED_MAX_MULTIPLICITY (9999) for "many".

ValueError: An enumeration cannot have two literals with the same name

Each EnumerationLiteral within an Enumeration must have a unique name.

TypeError: Expected Property instance, but got X

Association ends must be Property instances, not classes or strings. Each end should be: Property(name="...", type=SomeClass, multiplicity=Multiplicity(...)).

---

Validation Errors

model.validate() reports errors

DomainModel.validate() checks structural consistency:

Error message	Meaning	Fix
Generalization references class not in model	A Generalization uses a class that wasn't added to types	Add the missing class to the model's types set
Association end references type not in model	An association end's type class isn't in types	Add the class to types
Constraint context not in model	An OCL Constraint references a class not in types	Add the context class or remove the constraint
Circular inheritance detected	A → B → A inheritance loop	Fix the generalization chain

Always call model.validate() before running generators to catch these early.

OCL constraint validation failures

OCL constraints must:

1. Start with the context keyword (case-insensitive).
2. Contain at least one OCL keyword: inv, pre, post, self, collect, select, exists, forall, size.
3. Have balanced parentheses.

If the bocl library can't parse a constraint, it falls back to a regex-based parser. Complex OCL that neither parser handles will be reported as invalid but won't block generation.

Two distinct OCL failure classes — don't conflate them:

• Structural (blocking): a Constraint whose context class isn't in model.types is a model.validate() error — it fails validation and you should fix it before generating (see the table above).
• Expression (non-blocking): a constraint that is attached correctly but whose OCL text neither parser can evaluate is reported as invalid but does not block generation — generators that don't consume OCL run fine.

---

Generator Failures (quick reference)

This skill is the fast lookup for a generator error message: the table maps symptom → likely cause → first fix. For wrong-output debugging (a generator that runs but produces nothing or the wrong content) and per-generator deep dives, defer to the besser-generators skill's references/debugging.md.

Symptom	Likely cause	First fix
ValueError: Invalid DBMS	DBMS string is not one of sqlite, postgresql, mysql, mssql, mariadb, oracle	Use exactly postgresql (not postgres)
ValueError: Invalid backend (Qiskit)	backend_type is not aer_simulator, fake_backend, or ibm_quantum	Pick a valid backend
subprocess.CalledProcessError (Django)	Django not installed, project name conflict, or invalid Python identifier	python -m django --version; delete stale project; rename
AttributeError inside WebAppGenerator	gui_model=None was passed	Build a GUIModel first (see the besser-user skill's references/gui-models.md)
jinja2.TemplateNotFound	BESSER package corrupted or templates missing	pip install --force-reinstall besser
Raw [[ ]] in generated React files	ReactGenerator template rendering failed silently	Check console for Jinja errors; React uses [[ ]] to avoid JSX clashes

The Django generator catches subprocess errors and prints them rather than re-raising — if the generator "succeeded" but produced no project, scroll back through the console. (A generator that produces no file and no error is a debugging case → references/debugging.md in besser-generators.)

---

Docker and Deployment Issues

docker-compose up fails immediately

1. Docker daemon not running: Start Docker Desktop or the Docker service.
2. Port conflict: Default ports are 3000 (frontend), 8000 (backend), 8765 (agent). Check if something else is using them: lsof -i :8000 (Unix) or netstat -an | findstr 8000 (Windows).
3. Frontend submodule not initialized: If using the full BESSER repo with Docker Compose, the frontend submodule must be cloned:

   git submodule update --init --recursive
   

4. Missing .env file: The frontend build expects a .env file at besser/utilities/web_modeling_editor/frontend/packages/webapp/webpack/.env. Create one if missing.

docker-compose vs docker compose

BESSER's docker_deployment.py calls docker-compose (v1 with hyphen). If you only have Docker Compose v2 (plugin), either:

• Install docker-compose separately: pip install docker-compose
• Create an alias: alias docker-compose='docker compose'

Backend container can't find modules

The PYTHONPATH must be set to /app in the container. Check that docker-compose.yml has PYTHONPATH: /app in the backend service's environment.

ValueError: A different container is already running on port 8000

The deployment service detected a port conflict. Stop the existing container:

docker ps  # find the container using port 8000
docker stop <container_id>

Native dependencies fail in Docker

The base image python:3.11-slim doesn't include system libraries for psycopg2, pyodbc, etc. Add to the Dockerfile:

RUN apt-get update && apt-get install -y libpq-dev gcc

---

Model/Output Drift

When the generated code doesn't match what you expect from your model:

New attribute not appearing in generated code

1. Is the attribute actually in the class? print(my_class.attributes).
2. Is the class in the model? print(model.get_classes()).
3. Did you regenerate after adding the attribute?

Association not generating a foreign key

1. Check multiplicities — the generator uses multiplicity to decide which side gets the foreign key.
2. Check that both classes are in model.types and the association is in model.associations.
3. For many-to-many, a separate join table is generated.

Inheritance not reflected in generated code

1. Is the Generalization in model.generalizations?
2. Check the order: Generalization(general=Parent, specific=Child) — general is the parent, specific is the child.

Enumeration values wrong in generated code

1. Check literal names: print([lit.name for lit in my_enum.literals]).
2. Don't give an enum-typed attribute a default_value. It passes validate(), but the Pydantic/SQLAlchemy generators can't serialize an enum-literal default — they emit its raw repr() (the whole enum graph, with timestamps), so pydantic_classes.py / sql_alchemy.py won't even parse (SyntaxError: leading zeros in decimal integer literals are not permitted). Omit the default and set it in the app layer or as a DB column default. (Primitive defaults like True/0 are fine.)

---

Capturing Logs for Bug Reports

When filing a bug report, include:

1. Python version: python --version
2. BESSER version: pip show besser or check setup.cfg
3. Full traceback: Copy the complete error output
4. Minimal model: Reduce your model to the smallest example that reproduces the issue
5. Generator used: Which generator, with what options
6. Environment: OS, virtual environment type, Docker version if applicable

Creating a Minimal Reproduction

# minimal_repro.py
from besser.BUML.metamodel.structural import (
    DomainModel, Class, Property, BinaryAssociation,
    Multiplicity, StringType, IntegerType,
)
from besser.generators.sql_alchemy import SQLAlchemyGenerator

# Smallest model that triggers the bug
a = Class(name="A", attributes={Property(name="x", type=StringType)})
b = Class(name="B", attributes={Property(name="y", type=IntegerType)})
assoc = BinaryAssociation(name="a_b", ends={
    Property(name="a_end", type=a, multiplicity=Multiplicity(1, 1)),
    Property(name="b_end", type=b, multiplicity=Multiplicity(0, "*")),
})
model = DomainModel(name="repro", types={a, b}, associations={assoc})

# Validate first — validate() returns {"success": bool, "errors": [...], "warnings": [...]}
result = model.validate()
assert result["success"], result["errors"]

# Swap in whichever generator reproduces your bug
gen = SQLAlchemyGenerator(model=model, output_dir="./repro_output")
gen.generate(dbms="sqlite")

Run it: python minimal_repro.py. If it reproduces the bug, file it as an issue at https://github.com/BESSER-PEARL/BESSER/issues with the script and the full error output.

---

Quick Diagnostic Commands

# Check BESSER is importable
python -c "from besser.BUML.metamodel.structural import DomainModel; print('OK')"

# Check specific generator
python -c "from besser.generators.sql_alchemy import SQLAlchemyGenerator; print('OK')"

# Check OCL support
python -c "import bocl; print(f'bocl {bocl.__version__}')"

# Check Django
python -m django --version

# Check Docker
docker --version && docker compose version

# Run the library example to verify full stack
python tests/BUML/metamodel/structural/library/library.py

# Run tests
python -m pytest tests/ -x --tb=short