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:

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:

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:

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:

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.

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