ThrowException
ThrowException[spec]
creates and throws an Exception object from spec.
ThrowException[spec,payload]
creates and throws an Exception object from spec, with exception payload payload.
Details
- ThrowException[arg1,…] is always equivalent to ThrowException[Exception[arg1,…]].
- ThrowException always throws some Exception object.
- A typical usage scenario is to use ThrowException in internal functions to propagate exceptions and catch them in the user-facing functions with CatchExceptions.
- Possible forms of spec include:
-
tag a string or symbol, representing an exception tag {tag1,tag2,…} a list of several exception tags Exception[…] a valid exception object <…> an association containing full exception data - If spec is a tag or list of tags, each tag is added to the exception's resulting tag list together with all its parent tags. This process is referred to in the rest of this document as tag expansion.
- The payload may be any Wolfram Language expression, with an association being the most common case.
- If spec is an association, it must contain at least one of the following keys to be valid:
-
"ExceptionTagList" fully expanded list of exception tags "ExceptionTag" main exception tag - If payload is an association, the data it contains is added to the exception's data.
- If payload is an arbitrary expression, it is added to the exception's data as "ExceptionPayload"payload.
- If ThrowException is called outside any CatchException block, ThrowException generates an uncaught Exception message.
- When called with erroneous syntax, ThrowException throws an Exception object of type "ErrorHandlingException".
Examples
open all close allBasic Examples (1)
This throws an Exception object with a string tag and no additional information:
ThrowException["DataConsistencyError"]
This is exactly equivalent to the previous example:
ThrowException[Exception["DataConsistencyError"]]
This throws an Exception object with a string tag and some additional information:
ThrowException["DataConsistencyError", <|"Data" -> 42|>]
This throws an Exception object with a symbolic tag and some additional information:
Exception[ArgumentError, <|"SomeKey" -> "SomeValue"|>]Scope (2)
This registers an exception tag as a child type of another exception tag:
RegisterExceptionType[ArgumentTypeError, ArgumentError]This throws an Exception object with the registered tag:
ThrowException[ArgumentTypeError, <|"InvalidArgument" -> Pi, "ExpectedArgumentType" -> Integer|>]
This throws an Exception directly from exception data:
ThrowException[<|"ExceptionTagList" -> {ArgumentError}, "InvalidArgumentPosition" -> 2|>]
Possible Issues (3)
Throwing untagged exceptions is considered an error. The internal Exception is created and thrown in such cases:
ThrowException[1]
Throwing malformed exceptions is considered an error. The internal Exception is created and thrown in such cases:
ThrowException[1, 2, 3]
When calling ThrowException with two arguments, and the second argument (payload) is an association, a number of special keys it might have will be ignored/overwritten by the system:
ThrowException["Error", <|"ExceptionTag" -> "OtherError", "Data" -> 42|>]
Neat Examples (1)
Compute the first n primes, using exceptions to terminate the control flow when the requested number of results have been found:
firstPrimes[n_Integer] := Reap[
Module[{ctr = 0, $done},
CatchExceptions[$done]@
Do[
Which[ctr > n, ThrowException[$done], PrimeQ[i], Sow[i];ctr++], {i, 1, Infinity}]];, _, #2&][[2, 1]]firstPrimes[15]Text
Wolfram Research (2026), ThrowException, Wolfram Language function, https://reference.wolfram.com/language/ref/ThrowException.html.
CMS
Wolfram Language. 2026. "ThrowException." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/ThrowException.html.
APA
Wolfram Language. (2026). ThrowException. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/ThrowException.html