How to report a bug

A bug describes an existing feature that does not do what it should. Good bug reports help the team triage and reproduce issues fast.

Step 1 — Gather the facts

A useful bug report contains:

What you did — the exact steps to reproduce, including the scenario, the feature you ran, and any non-default parameters.
What you expected to happen.
What actually happened — the full error message, including the stack trace if Python raised an exception.
Your environment — CEA version (visible in the dashboard footer, or cea --version), OS, and how you installed CEA (Pixi, Docker, NSIS installer).

Open the repository’s Issues tab: https://github.com/architecture-building-systems/CityEnergyAnalyst/issues.
Click New issue and choose the Bug report template (.github/ISSUE_TEMPLATE/bug_report.yml).
Fill in the template fields. The title should be short and identify both the affected area and the CEA version, e.g. “Optimisation crashes on Windows with multi-CPU in CEA 4.0.0-beta.7”.
Reference related issues with #1234 and people with @username if helpful.

Search existing issues — your bug may already be filed.
Check the Known Issues page.
Ask in Discussions if you’re unsure whether it’s a bug or an expected behaviour.