WOLFRAM

Wolfram Language & System Documentation Center

Failure["tag",assoc]

represents a failure of a type indicated by tag, with details given by the association assoc.

Details
Details and Options Details and Options
Examples  
Basic Examples  
Scope  
Basic Uses  
Properties  
Properties & Relations  
Neat Examples  
See Also
Related Guides
History
Cite this Page

Failure

Failure["tag",assoc]

represents a failure of a type indicated by tag, with details given by the association assoc.

Details

  • Failure[…]["prop"] extracts a property from a Failure object. Failure[…][{key1,key2,…}] extracts a list of values. »
  • Failure[…]["Properties"] returns a list of available properties. »
  • The association assoc typically includes:
  • "MessageTemplate"a string template for a message
    "MessageParameters"parameters to use for the message template
  • The parameters are effectively inserted into the message template using TemplateApply.
  • With the entry "MessageTemplate":>symb::name a message name can be stored for use when a message is generated.
  • Failure is generated by Interpreter and related functions. Possible tags in this case are "InterpretationFailure", "RestrictionFailure", "ConditionFailure", and "ConnectionFailure".

Examples

open all close all

Basic Examples  (2)

A typical way in which Failure is generated:

Wolfram Language code: Interpreter["Integer"]["notnumber"]

Show the underlying structure:

Wolfram Language code: InputForm[%]

Manually construct a failure:

Wolfram Language code: Failure["InvalidRange", <| "MessageTemplate" -> "Enter a number lower than `Number`", "MessageParameters" -> <|"Number" -> 10|> |>]

Scope  (10)

Basic Uses  (6)

Create a Failure using only a tag:

Wolfram Language code: Failure["InvalidInput", <||>]

Use a tag and a message:

Wolfram Language code: Failure["InvalidInput", <|"Message" -> "Input must be a string"|>]

Use a template with positional parameters:

Wolfram Language code: Failure["ExternalOperation", <|"MessageTemplate" -> "External operation `1` failed.", "MessageParameters" -> { "file upload"}|>]

Indicate a failure using a StringTemplate:

Wolfram Language code: Failure["InvalidRange", <| "MessageTemplate" -> StringTemplate["Enter a number lower than `Number`"], "MessageParameters" -> <|"Number" -> 10|>|>]

Indicate a failure using MessageName:

Wolfram Language code: MyFunc::nvldrange = "Enter a number greater than `Number`"; Failure["InvalidRange", <|"MessageTemplate" -> MyFunc::nvldrange, "MessageParameters" -> <|"Number" -> 10|>|>]

Failure can contain metadata:

Wolfram Language code: Failure["RestrictionFailure", <|"MessageTemplate" :> Interpreter::numberinterval, "MessageParameters" -> <|"Min" -> "1", "Max" -> "10", "Input" -> {"100"}|>, "Interval" -> Interval[{1, 10}], "Input" -> {"100"}, "Type" -> "Number"|> ]

Properties  (4)

Get a list of all the available properties:

Wolfram Language code: f = Failure["RestrictionFailure", Association["MessageTemplate" :> Interpreter::numberinterval, "MessageParameters" -> Association["Min" -> "1", "Max" -> "10", "Input" -> {"100"}], "Interval" -> Interval[{1, 10}], "Input" -> {"100"}, "Type" -> "Number"]];
Wolfram Language code: f["Properties"]

Extract the "Input" property:

Wolfram Language code: f["Input"]

Extract the message template, name and parameters:

Wolfram Language code: f = Failure["RestrictionFailure", Association["MessageTemplate" :> Interpreter::numberinterval, "MessageParameters" -> Association["Min" -> "1", "Max" -> "10", "Input" -> {"100"}], "Interval" -> Interval[{1, 10}], "Input" -> {"100"}, "Type" -> "Number"]];
Wolfram Language code: f[{"MessageTemplate", "MessageName", "MessageParameters"}]

Extract the message template without evaluating it:

Wolfram Language code: f = Failure["RestrictionFailure", Association["MessageTemplate" :> Interpreter::numberinterval, "MessageParameters" -> Association["Min" -> "1", "Max" -> "10", "Input" -> {"100"}], "Interval" -> Interval[{1, 10}], "Input" -> {"100"}, "Type" -> "Number"]];
Wolfram Language code: f["HeldMessageTemplate"]

Extract the actual error message:

Wolfram Language code: f = Failure["RestrictionFailure", Association["MessageTemplate" :> Interpreter::numberinterval, "MessageParameters" -> Association["Min" -> "1", "Max" -> "10", "Input" -> {"100"}], "Interval" -> Interval[{1, 10}], "Input" -> {"100"}, "Type" -> "Number"]];
Wolfram Language code: f["Message"]
Wolfram Language code: f["StyledMessage"]

Properties & Relations  (4)

Use ToString to get the formatted message:

Wolfram Language code: f = Interpreter["Number"]["hello"];
Wolfram Language code: f // ToString

This is equivalent to the "Message" property:

Wolfram Language code: f["Message"]

Failure is returned by functions like SendMail and EntityPrefetch:

Wolfram Language code: EntityPrefetch["NoSuchEntity"]

For these functions, the opposite of Failure is Success:

Wolfram Language code: EntityPrefetch["Planet"]

Failure expressions are FailureQ:

Wolfram Language code: FailureQ[Failure["InterpretationFailure", Association["MessageTemplate" :> Interpreter::number, "MessageParameters" -> Association["Input" -> "notnumber"], "Input" -> "notnumber", "Type" -> "Integer"]]]

Using an Association with Rule will embed the evaluated expression into the Failure expression:

Wolfram Language code: MyFunc::nvldrange = "Enter a number greater than `Number`";
Wolfram Language code: Failure["InvalidRange", <|"MessageTemplate" -> MyFunc::nvldrange|>]; %["HeldMessageTemplate"]

Use RuleDelayed to prevent evaluation:

Wolfram Language code: Failure["InvalidRange", <|"MessageTemplate" :> MyFunc::nvldrange|>]; %["HeldMessageTemplate"]

Neat Examples  (1)

Generate a dataset with all the properties of a Failure expression:

Wolfram Language code: f = Failure["RestrictionFailure", Association["MessageTemplate" :> Interpreter::numberinterval, "MessageParameters" -> Association["Min" -> "1", "Max" -> "10", "Input" -> {"100"}], "Interval" -> Interval[{1, 10}], "Input" -> {"100"}, "Type" -> "Number"]];
Wolfram Language code: AssociationMap[f, f["Properties"]]//Dataset
Wolfram Research (2014), Failure, Wolfram Language function, https://reference.wolfram.com/language/ref/Failure.html.

Text

Wolfram Research (2014), Failure, Wolfram Language function, https://reference.wolfram.com/language/ref/Failure.html.

CMS

Wolfram Language. 2014. "Failure." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/Failure.html.

APA

Wolfram Language. (2014). Failure. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/Failure.html

BibTeX

@misc{reference.wolfram_2026_failure, author="Wolfram Research", title="{Failure}", year="2014", howpublished="\url{https://reference.wolfram.com/language/ref/Failure.html}", note=[Accessed: 12-June-2026]}

BibLaTeX

@online{reference.wolfram_2026_failure, organization={Wolfram Research}, title={Failure}, year={2014}, url={https://reference.wolfram.com/language/ref/Failure.html}, note=[Accessed: 12-June-2026]}