What does the error function do in MATLAB / RunMat?

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 does the error function behave in MATLAB / RunMat?

• error(message) throws using the default identifier MATLAB:error.
• error(id, message) uses a custom identifier. Identifiers are normalised to MATLAB:* 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 MATLAB: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.

GPU execution and residency

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.

Examples of using the error function in MATLAB / RunMat

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("MATLAB:demo:badValue", "Value %d is outside [%d, %d].", value, 0, 10);
catch err
    disp(err.message);
end

Rethrowing an existing MException

try
    try
        error("MATLAB: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

1. How do I choose a custom identifier? Use component:mnemonic style strings such as "MATLAB:io:fileNotFound" or "runmat:tools:badInput". If you omit a namespace (:), RunMat prefixes the identifier with MATLAB: automatically.
2. Can I rethrow an existing MException? Yes. Pass the object returned by catch err directly to error(err) to propagate it unchanged.
3. What happens if I pass extra arguments after an MException or struct? RunMat treats that as invalid usage and raises MATLAB:error explaining that no additional arguments are allowed in those forms.
4. 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.
5. What if I call error without arguments? RunMat raises MATLAB:error indicating that a message is required, matching MATLAB's behaviour.
6. Why was my identifier normalised to MATLAB:...? 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.
7. Can the message span multiple lines? Yes. Any newline characters in the formatted message are preserved exactly in the thrown exception.
8. Does formatting follow MATLAB rules? Yes. error uses the same formatter as sprintf, including width/precision specifiers and numeric conversions, and will raise MATLAB:error if the format string is invalid or under-specified.