`error` — Throw an exception with an identifier and a formatted diagnostic message.

error throws an exception immediately, unwinding the current execution frame and transferring control to the nearest catch block (or aborting the program if none exists). RunMat mirrors MATLAB's behaviour, including support for message identifiers, formatted messages, MException objects, and legacy message structs.

How `error` works in RunMat

error(message) throws using the default identifier RunMat:error.
error(id, message) uses a custom identifier. Identifiers are normalised to RunMat:* when they do not already contain a namespace.
error(fmt, arg1, ...) formats the message with MATLAB's sprintf rules before throwing.
error(id, fmt, arg1, ...) combines both a custom identifier and formatted message text.
error(MException_obj) rethrows an existing exception without altering its identifier or message.
error(struct('identifier', id, 'message', msg)) honours the legacy structure form.
Invalid invocations (missing message, extra arguments after an MException, malformed structs, etc.) themselves raise RunMat:error diagnostics so the caller can correct usage. The thrown exception is observed in MATLAB-compatible try/catch constructs or by the embedding runtime, which converts the string back into an MException object.

How `error` runs on the GPU

error is a control-flow builtin and never executes on the GPU. When formatting messages that include GPU-resident arrays (for example, via %g or %s specifiers), RunMat first gathers those values back to host memory so that the final diagnostic message accurately reflects the data the user passed.

GPU memory and residency

Examples

Throwing an error with a simple message

try
    error("Computation failed.");
catch err
    fprintf("%s -> %s\n", err.identifier, err.message);
end

Throwing an error with a custom identifier

try
    error("runmat:examples:invalidState", "State vector is empty.");
catch err
    fprintf("%s\n", err.identifier);
end

Formatting values inside the error message

value = 42;
try
    error("RunMat:demo:badValue", "Value %d is outside [%d, %d].", value, 0, 10);
catch err
    disp(err.message);
end

Rethrowing an existing MException

try
    try
        error("RunMat:inner:failure", "Inner failure.");
    catch inner
        error(inner); % propagate with original identifier/message
    end
catch err
    fprintf("%s\n", err.identifier);
end

Using a legacy message struct

S.identifier = "toolbox:demo:badInput";
S.message = "Inputs must be positive integers.";
try
    error(S);
catch err
    fprintf("%s\n", err.identifier);
end

FAQ

How do I choose a custom identifier?

Use component:mnemonic style strings such as "RunMat:io:fileNotFound" or "runmat:tools:badInput". If you omit a namespace (:), RunMat prefixes the identifier with RunMat: automatically.

Can I rethrow an existing `MException`?

Yes. Pass the object returned by catch err directly to error(err) to propagate it unchanged.

What happens if I pass extra arguments after an `MException` or struct?

RunMat treats that as invalid usage and raises RunMat:error explaining that no additional arguments are allowed in those forms.

Does `error` run on the GPU?

No. The builtin executes on the host. If the message references GPU data, RunMat gathers the values before formatting the diagnostic string.

What if I call `error` without arguments?

RunMat raises RunMat:error indicating that a message is required, matching MATLAB's behaviour.

Why was my identifier normalised to `RunMat:...`?

MATLAB requires message identifiers to contain at least one namespace separator (:). RunMat enforces this rule so diagnostics integrate cleanly with tooling that expects fully-qualified identifiers.

Can the message span multiple lines?

Yes. Any newline characters in the formatted message are preserved exactly in the thrown exception.

Does formatting follow MATLAB rules?

Yes. error uses the same formatter as sprintf, including width/precision specifiers and numeric conversions, and will raise RunMat:error if the format string is invalid or under-specified. #

These functions work well alongside error. Each page has runnable examples you can try in the browser.

assert, warning

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how error works, line by line, in Rust.

View error.rs on GitHub
Learn how the runtime works
Found a bug? Open an issue with a minimal reproduction.

About RunMat

RunMat is an open-source runtime that executes MATLAB-syntax code — faster, on any GPU, with no license required.

Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing

error — Throw an exception with an identifier and a formatted diagnostic message.

How error works in RunMat

How error runs on the GPU