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.

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:

``bash git submodule update --init --recursive ``

1. 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 

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.

1. Check that both classes are in model.types and the association is in

model.associations.

1. 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: BESSER-PEARL
• Source: BESSER-PEARL/BESSER-Skills
• License: Apache-2.0
• Homepage: https://besser.readthedocs.io

Install and usage instructions live in the source repository linked above.