# How to Handle Errors and Use the error_manager Module in Nelson

> Master error handling in Nelson with error_manager. Learn to bridge C++ exceptions and script functions like error warning and throw for robust code. Discover how.

- Repository: [The Nelson Programming Language/nelson](https://github.com/nelson-lang/nelson)
- Tags: how-to-guide
- Published: 2026-03-08

---

**The `error_manager` module in Nelson provides a MATLAB-compatible error-handling infrastructure that bridges low-level C++ exceptions with high-level script functions like `error`, `warning`, `throw`, `lasterror`, and `lastwarn`.**

The nelson-lang/nelson repository implements a robust error-handling system that allows developers to handle errors and use the error_manager module in Nelson scripts through both simple function calls and advanced exception management. This architecture captures stack traces, supports warning states, and enables precise error filtering through the `MException` class.

## Architecture of the error_manager Module

The error_manager module operates across four distinct architectural layers that translate between C++ exceptions and script-level error objects.

The **Public C++ API** layer, defined in [`modules/error_manager/src/include/Error.hpp`](https://github.com/nelson-lang/nelson/blob/main/modules/error_manager/src/include/Error.hpp) and [`Error.cpp`](https://github.com/nelson-lang/nelson/blob/main/Error.cpp), provides the `Error()` and `Warning()` functions. These capture the current call stack from the `Evaluator` and throw `Nelson::Exception` objects. The **Exception type** layer implements `MException` in [`MException.hpp`](https://github.com/nelson-lang/nelson/blob/main/MException.hpp), providing MATLAB-compatible conversion helpers like `ArrayOfToException` and `ExceptionToArrayOf` that translate between C++ exceptions and script structs.

The **Gateway layer** contains builtin implementations such as [`throwBuiltin.cpp`](https://github.com/nelson-lang/nelson/blob/main/throwBuiltin.cpp) and [`warningBuiltin.cpp`](https://github.com/nelson-lang/nelson/blob/main/warningBuiltin.cpp) that parse script arguments and invoke the C++ API. This layer also manages warning state machinery through `warning('on')`, `warning('off')`, and `warning('aserror')` commands. Finally, the **State storage** layer uses the `NelsonConfiguration` singleton to persist the last warning exception and warning-state maps, enabling `lastwarn` and `lasterror` functionality.

## Raising Errors and Warnings in Nelson Scripts

### Raising a Simple Error

When a script calls `error('message')`, the builtin gateway in [`modules/error_manager/builtin/cpp/errorBuiltin.cpp`](https://github.com/nelson-lang/nelson/blob/main/modules/error_manager/builtin/cpp/errorBuiltin.cpp) forwards the request to the C++ `Error` function. This constructs a `DebugStack` from the current call stack and throws a `Nelson::Exception`, halting execution immediately.

```matlab
% Raise a fatal error
error('File not found');

```

The interpreter catches the C++ exception and displays:

```

Error: File not found

```

### Configuring Warnings as Errors

The `warning` function controls emission behavior through three states: `on`, `off`, and `aserror`. In [`warningBuiltin.cpp`](https://github.com/nelson-lang/nelson/blob/main/warningBuiltin.cpp), the gateway stores states in `NelsonConfiguration`. When `warning('aserror', 'id')` is set, the `Warning` C++ class checks the state via `warningCheckState()` and routes to `Error()` instead of emitting a warning.

```matlab
% Set warning "my:warn" to behave as an error
warning('on')          % default – enabled
warning('aserror','my:warn');

% This now raises an error instead of a warning
warning('my:warn','Something is odd');

```

### Throwing MException Objects

The `throw` function re-raises existing `MException` objects while preserving the original identifier and message. The implementation in [`throwBuiltin.cpp`](https://github.com/nelson-lang/nelson/blob/main/throwBuiltin.cpp) detects scalar `MException` structs, uses `ArrayOfToException` to convert back to a C++ `Exception`, attaches the current stack trace via `DebugStack(eval->callstack,1,trace)`, and re-throws.

```matlab
% Create an MException
ME = MException('my:Error','Bad value');
% Re-throw it
throw(ME);

```

## Capturing and Querying Errors

### Using Try-Catch Blocks

Nelson supports MATLAB-compatible `try-catch` syntax. When the interpreter catches a C++ exception, it converts the `Exception` to an `MException` struct using `ExceptionToArrayOf`, making the `message`, `identifier`, and `stack` fields available in the catch clause.

```matlab
try
    error('Oops');
catch ME
    disp(['Caught: ' ME.message]);   % prints "Caught: Oops"
    disp(['Identifier: ' ME.identifier]); % prints "Identifier: "
end

```

### Retrieving Last Warning and Error States

The `lastwarn` and `lasterror` functions query persistent state stored in the `NelsonConfiguration` singleton. `lastwarn` retrieves the most recent warning exception, while `lasterror` accesses the last caught exception from the evaluator.

```matlab
% Emit a warning
warning('my:warn', 'Something');

% Retrieve it
[wmsg, wid] = lastwarn;  % wmsg = "Something", wid = "my:warn"

% Retrieve last error after catch
try
    error('Bad');
catch
    e = lasterror;
    disp(e.message);   % "Bad"
    disp(e.identifier);% ""
end

```

## Key Implementation Files

The error_manager module spans several critical paths in the nelson-lang/nelson repository:

- **[`modules/error_manager/src/include/Error.hpp`](https://github.com/nelson-lang/nelson/blob/main/modules/error_manager/src/include/Error.hpp)** and **[`Error.cpp`](https://github.com/nelson-lang/nelson/blob/main/Error.cpp)** – Core C++ API for raising errors with stack trace capture via `DebugStack`.
- **[`modules/error_manager/src/include/Warning.hpp`](https://github.com/nelson-lang/nelson/blob/main/modules/error_manager/src/include/Warning.hpp)** and **[`Warning.cpp`](https://github.com/nelson-lang/nelson/blob/main/Warning.cpp)** – Warning emission logic, state checking via `warningCheckState`, and conversion to error when configured as `aserror`.
- **[`modules/error_manager/src/include/MException.hpp`](https://github.com/nelson-lang/nelson/blob/main/modules/error_manager/src/include/MException.hpp)** – Conversion utilities `ArrayOfToException` and `ExceptionToArrayOf` between C++ exceptions and script structs.
- **[`modules/error_manager/builtin/cpp/throwBuiltin.cpp`](https://github.com/nelson-lang/nelson/blob/main/modules/error_manager/builtin/cpp/throwBuiltin.cpp)** – Script-level `throw` implementation for re-raising `MException` objects.
- **[`modules/error_manager/builtin/cpp/warningBuiltin.cpp`](https://github.com/nelson-lang/nelson/blob/main/modules/error_manager/builtin/cpp/warningBuiltin.cpp)** – Gateway for `warning` state management and emission modes.
- **`modules/error_manager/help/en_US/xml/`** – Documentation source files for user-facing error handling functions.

## Summary

- The **error_manager** module provides Nelson's complete error-handling infrastructure, bridging low-level C++ exceptions with high-level script functions through the `Error` and `Warning` classes.
- Use **`error('msg')`** for fatal errors and **`warning('msg')`** for recoverable issues, with **`warning('aserror','id')`** to upgrade specific warnings to errors.
- Capture exceptions using **`try-catch`** blocks where the catch variable receives an **MException** struct containing **message**, **identifier**, and **stack** fields.
- Query recent errors and warnings via **`lasterror`** and **`lastwarn`**, which access state stored in the core **NelsonConfiguration** singleton.

## Frequently Asked Questions

### How do I convert a warning into a fatal error in Nelson?

Use the **`warning('aserror', 'identifier')`** syntax to map a specific warning ID to error behavior. When that warning is subsequently triggered, the `Warning` C++ class in [`Warning.cpp`](https://github.com/nelson-lang/nelson/blob/main/Warning.cpp) checks the state via `warningCheckState` and routes to the `Error` function, causing execution to halt immediately rather than continuing with a warning message.

### What is the difference between `error` and `throw` in Nelson?

The **`error`** function creates a new exception with the current call stack and immediately halts execution. The **`throw`** function re-raises an existing **MException** object, preserving its original identifier and message while attaching the current stack trace via `DebugStack` in [`throwBuiltin.cpp`](https://github.com/nelson-lang/nelson/blob/main/throwBuiltin.cpp)—useful for re-throwing exceptions in catch blocks without losing the original error context.

### How does Nelson store the last warning and error states?

Nelson uses the **NelsonConfiguration** singleton to persist state across the interpreter session. The `lastwarn` function retrieves the most recent warning exception from this configuration, while `lasterror` accesses the last caught exception from the evaluator's state. These functions enable scripts to inspect errors after they occur or outside of immediate try-catch blocks.

### Can I customize the identifier when raising an error?

Yes. While the simple **`error('message')`** form uses an empty identifier, you can create custom exceptions with specific identifiers using the **MException** class. Construct the exception with **`MException('identifier', 'message')`** and then use **`throw(ME)`** to raise it with the custom identifier intact, enabling precise error filtering in catch blocks based on the `identifier` field.