`error` — Throw exceptions with identifiers and formatted messages in MATLAB and RunMat.

error throws an exception immediately, unwinding the current execution frame to the nearest catch (or aborting if none exists). Identifier, formatting, and exception-object behavior follow MATLAB semantics.

Syntax

out = error(message)
out = error(message, A...)
out = error(message_id, message)
out = error(message_id, message, A...)
out = error(mex)
out = error(msg_struct)

Inputs

Name	Type	Required	Default	Description
`message`	`StringScalar`	Yes	—	Error message text.
`message`	`StringScalar`	Yes	—	Error message template text.
`A`	`Any`	Variadic	—	Formatting values for the message template.
`message_id`	`StringScalar`	Yes	`"RunMat:error"`	Message identifier.
`mex`	`Any`	Yes	—	MException value to rethrow.
`msg_struct`	`Any`	Yes	—	Struct containing identifier/message fields.

Returns

Name	Type	Description
`out`	`Any`	Never returned because error always throws.

Errors

Identifier	When	Message
`RunMat:error`	No arguments are supplied.	`error: missing message argument`
`RunMat:error`	Additional arguments are supplied after an MException input.	`error: additional arguments are not allowed when passing an MException`
`RunMat:error`	Additional arguments are supplied after a message-struct input.	`error: additional arguments are not allowed when passing a message struct`
`RunMat:error`	Message struct does not contain an identifier field.	`error: message struct must contain an 'identifier' field`
`RunMat:error`	Message struct does not contain a message field.	`error: message struct must contain a 'message' field`
`RunMat:error`	Identifier/message inputs or format arguments are not string-compatible.	`error: invalid input argument`

How `error` works

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.

Does RunMat run `error` 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

Using `error` with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how error changes the result.

Run a small error example, explain the result, then change one input and compare the output.

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

assert · rethrow · warning

Open-source implementation

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

View the source for error in Rust on GitHub
Learn how the RunMat 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 blazing on any GPU. It is licensed under the Apache 2.0 license.

RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.

Getting started · Benchmarks · Pricing

error — Throw exceptions with identifiers and formatted messages in MATLAB and RunMat.