Feat: Introduce dedicated exception hierarchy in mesa/errors.py by codebreaker32 · Pull Request #2992 · mesa/mesa

codebreaker32 · 2025-12-23T08:12:03Z

This PR introduces a new module, mesa/errors.py, which defines a dedicated and structured exception hierarchy for the Mesa framework. It establishes a base MesaError class and categorizes specific exceptions for Models, Spaces, Scheduling, and Visualization.

Currently, the Mesa codebase relies heavily on generic Python exceptions (such as ValueError, AttributeError, and RuntimeError) to handle failure states.

This creates several issues:

Ambiguity: It is difficult for users to distinguish between a Python syntax error and a specific Mesa logic violation.
Hard to Catch: Users cannot programmatically catch specific framework errors (e.g., "Agent out of bounds") without writing fragile string-matching logic against ValueError messages.
Debugging: Generic errors do not inherently provide context about the Mesa version or the specific subsystem that failed.
This PR solves this by providing a standardized set of exceptions that offer semantic meaning to errors.

Implementation

Created mesa/errors.py.

Defined a base class MesaError which automatically prepends the installed Mesa version to all error messages to assist with issue reporting.

Implemented semantic grouping for exceptions:

Model/Config: ConfigurationError, SeedError.
Agent: Agent Related Errors/Exceptions(primaly state errors)
Space: GridDimensionError, OutOfBoundsError, PropertyLayerErrors(a lot of them).
Time: ScheduleError, EventSchedulingError.
Visualization: UserInputError.

Usage Examples

Note: This PR only adds the definitions(to keep it simple for review). In upcoming PRs, I will be updating the codebase will be updated to usage patterns like this:

Improved Error Handling for Users

from mesa.errors import OutOfBoundsError

try:
    grid.move_agent(agent, (999, 999))
except OutOfBoundsError as e:
    # We know exactly what went wrong and can handle it gracefully
    # ....Logic to Handle

Clearer Debugging Output Instead of ValueError( or generic errors)

mesa.errors.GridDimensionError: [Mesa 3.0] Dimensions must be a list of positive integers.

Future Work Plan: I will be opening multiple follow-up PRs to incrementally refactor the codebase to use these new errors.

for more information, see https://pre-commit.ci

github-actions · 2025-12-23T08:19:06Z

Performance benchmarks:

Model	Size	Init time [95% CI]	Run time [95% CI]
BoltzmannWealth	small	🔵 -0.9% [-1.8%, +0.1%]	🔵 +0.2% [+0.1%, +0.3%]
BoltzmannWealth	large	🔵 +1.6% [-2.1%, +7.5%]	🔵 -4.3% [-6.2%, -2.7%]
Schelling	small	🔵 -0.2% [-1.9%, +1.6%]	🔵 -0.7% [-1.7%, +0.3%]
Schelling	large	🔵 +1.0% [-0.3%, +3.6%]	🔵 -0.2% [-1.4%, +0.7%]
WolfSheep	small	🔵 +0.1% [-1.1%, +0.9%]	🔵 -0.3% [-0.4%, -0.2%]
WolfSheep	large	🔵 -2.0% [-7.2%, +0.8%]	🔵 +1.4% [+0.1%, +2.5%]
BoidFlockers	small	🔵 +1.6% [+1.2%, +1.9%]	🔵 +2.5% [+2.3%, +2.7%]
BoidFlockers	large	🔵 +1.1% [+0.8%, +1.4%]	🔵 +2.2% [+2.0%, +2.4%]

for more information, see https://pre-commit.ci

codebreaker32 · 2025-12-23T10:12:13Z

Hi @EwoutH @quaquel
I would love to have your reviews on this

quaquel · 2025-12-23T22:18:07Z

Thanks for this. I still need to decide how to proceed with exceptions in MESA. I believe this is a topic that warrants further discussion. For example, there are a bunch of errors in MESA that might also justifiably be subclassed from default Python errors. I don't know what the recommended practice is in Python and would like to read upcommit on this before ting to any specific approach.

quaquel · 2025-12-29T13:13:33Z

I have opened a discussion on mesa exceptions in the mesa 4.0 discussion. I am closing this PR, but included a link to it there. Depending on how we decide to move forward, we might reopen this or least draw heavily from it.

Nithurshen · 2026-01-22T02:38:32Z

@codebreaker32, Hello.
I am closely following the discussion on Exceptions for Mesa 4.0. I have experience working on exceptions in other python-based frameworks before. It was me who suggested a exception hierarchy.
I would like to work on the exceptions when a consensus is reached. Is that okay?
Thank you

codebreaker32 · 2026-01-22T07:36:00Z

Good to know this, @Nithurshen. You’re welcome to take a stab at it, but I’d suggest first dropping your ideas on #2972 (comment)
The direction isn’t fully crystallized yet (see the comment on #3146), so aligning there first will help us move forward coherently.

Nithurshen · 2026-01-22T08:25:41Z

Good to know this, @Nithurshen. You’re welcome to take a stab at it, but I’d suggest first dropping your ideas on #2972 (comment) The direction isn’t fully crystallized yet (see the comment on #3146), so aligning there first will help us move forward coherently.

It's quite funny. But thank you for your support.
But I'd suggest you to read the whole thread, as I was the one who suggested this idea.

EwoutH · 2026-01-22T08:30:10Z

I think it’s good to open a separate discussion thread for error types in Mesa. Then we can follow our development process https://github.com/mesa/mesa/blob/main/CONTRIBUTING.md#mesa-development-process

codebreaker32 · 2026-01-22T09:37:20Z

My apologies if that came across wrong, @Nithurshen . I wasn't overlooking your previous work on this, I was referring specifically to @quaquel recent note in #3146 about pausing new PRs until we have a consensus.

Since @EwoutH has suggested opening a separate discussion thread, that seems like the best place to finalize the direction. Would be great to see your proposal there :)

quaquel · 2026-01-22T16:26:50Z

I'd say there is consensus on the basic idea. Now it's more a matter of fleshing out the details and agreeing on a process. One option is to fully assess the current code and identify all places where a special mesa exception might be useful. The other option is to take a more piecemeal approach. I don't know yet which is better. Also, we might want to establish some basic guidelines for deciding which exception to use.

Nithurshen · 2026-01-23T03:44:31Z

I'd say there is consensus on the basic idea. Now it's more a matter of fleshing out the details and agreeing on a process. One option is to fully assess the current code and identify all places where a special mesa exception might be useful. The other option is to take a more piecemeal approach. I don't know yet which is better. Also, we might want to establish some basic guidelines for deciding which exception to use.

Is it fine if we open a separate discussion thread like @EwoutH suggested?

quaquel · 2026-01-23T07:35:30Z

Is it fine if we open a separate discussion thread like @EwoutH suggested?

Of course

Nithurshen · 2026-01-23T08:59:04Z

@EwoutH @quaquel
I have opened a separate discussion thread.

codebreaker32 and others added 3 commits December 23, 2025 08:07

Add base Error class for Mesa specific errors

8bea8f8

Merge branch 'mesa:main' into feat/add-errors

f069aeb

[pre-commit.ci] auto fixes from pre-commit.com hooks

d2221b9

for more information, see https://pre-commit.ci

codebreaker32 and others added 3 commits December 23, 2025 13:51

Fix pre-commit.ci errors

0832158

[pre-commit.ci] auto fixes from pre-commit.com hooks

bb16dec

for more information, see https://pre-commit.ci

Merge branch 'main' into feat/add-errors

0249c63

Merge branch 'main' into feat/add-errors

adc4b81

quaquel closed this Dec 29, 2025

EwoutH mentioned this pull request Jan 14, 2026

Mesa 4 development tracking issue #3132

Open

42 tasks

navneetkumaryadav207001 mentioned this pull request Jan 16, 2026

Feat: Introduce minimal Mesa-specific exception hierarchy in mesa/errors.py #3146

Closed

codebreaker32 deleted the feat/add-errors branch February 17, 2026 16:46

Uh oh!

Conversation

codebreaker32 commented Dec 23, 2025

Implementation

Usage Examples

Uh oh!

github-actions bot commented Dec 23, 2025

Uh oh!

codebreaker32 commented Dec 23, 2025

Uh oh!

quaquel commented Dec 23, 2025

Uh oh!

quaquel commented Dec 29, 2025

Uh oh!

Nithurshen commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codebreaker32 commented Jan 22, 2026

Uh oh!

Nithurshen commented Jan 22, 2026

Uh oh!

EwoutH commented Jan 22, 2026

Uh oh!

codebreaker32 commented Jan 22, 2026

Uh oh!

quaquel commented Jan 22, 2026

Uh oh!

Nithurshen commented Jan 23, 2026

Uh oh!

quaquel commented Jan 23, 2026

Uh oh!

Nithurshen commented Jan 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Nithurshen commented Jan 22, 2026 •

edited

Loading