---
title: "Failure"
language: "en"
type: "Symbol"
summary: "Failure[tag, assoc] represents a failure of a type indicated by tag, with details given by the association assoc."
keywords: 
- failure
- failure mode
- failure type
- error handling
- failure message
- failure reporting
canonical_url: "https://reference.wolfram.com/language/ref/Failure.html"
source: "Wolfram Language Documentation"
related_guides: 
  - 
    title: "Creating Form Interfaces & Apps"
    link: "https://reference.wolfram.com/language/guide/CreatingFormsAndApps.en.md"
  - 
    title: "Creating Instant APIs"
    link: "https://reference.wolfram.com/language/guide/CreatingAnInstantAPI.en.md"
  - 
    title: "Package Development"
    link: "https://reference.wolfram.com/language/guide/PackageDevelopment.en.md"
  - 
    title: "Setting Up Input Interpreters"
    link: "https://reference.wolfram.com/language/guide/InterpretingStrings.en.md"
  - 
    title: "Messages"
    link: "https://reference.wolfram.com/language/guide/Messages.en.md"
  - 
    title: "Free-Form & External Input"
    link: "https://reference.wolfram.com/language/guide/FreeFormAndExternalInput.en.md"
  - 
    title: "Robustness & Error Handling"
    link: "https://reference.wolfram.com/language/guide/RobustnessAndErrorHandling.en.md"
  - 
    title: "Automatic Mail Processing"
    link: "https://reference.wolfram.com/language/guide/AutomaticMailProcessing.en.md"
related_functions: 
  - 
    title: "Confirm"
    link: "https://reference.wolfram.com/language/ref/Confirm.en.md"
  - 
    title: "Interpreter"
    link: "https://reference.wolfram.com/language/ref/Interpreter.en.md"
  - 
    title: "$Failed"
    link: "https://reference.wolfram.com/language/ref/$Failed.en.md"
  - 
    title: "FailureQ"
    link: "https://reference.wolfram.com/language/ref/FailureQ.en.md"
  - 
    title: "Message"
    link: "https://reference.wolfram.com/language/ref/Message.en.md"
  - 
    title: "Success"
    link: "https://reference.wolfram.com/language/ref/Success.en.md"
  - 
    title: "If"
    link: "https://reference.wolfram.com/language/ref/If.en.md"
  - 
    title: "Assert"
    link: "https://reference.wolfram.com/language/ref/Assert.en.md"
  - 
    title: "Missing"
    link: "https://reference.wolfram.com/language/ref/Missing.en.md"
  - 
    title: "StringTemplate"
    link: "https://reference.wolfram.com/language/ref/StringTemplate.en.md"
  - 
    title: "TerminatedEvaluation"
    link: "https://reference.wolfram.com/language/ref/TerminatedEvaluation.en.md"
---
# 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 (17)

### Basic Examples (2)

A typical way in which ``Failure`` is generated:

```wl
In[1]:= Interpreter["Integer"]["notnumber"]

Out[1]=
Failure["InterpretationFailure", Association["MessageTemplate" :> Interpreter::number, 
  "MessageParameters" -> Association["Input" -> {"notnumber"}], "Input" -> {"notnumber"}, 
  "Type" -> "Integer"]]
```

Show the underlying structure:

```wl
In[2]:= InputForm[%]
```

Out[2]//InputForm=
Failure["InterpretationFailure", <\|"MessageTemplate" :> Interpreter::number, 
  "MessageParameters" -> <\|"Input" -> {"notnumber"}\|>, "Input" -> {"notnumber"}, "Type" -> "Integer"\|>]

---

Manually construct a failure:

```wl
In[1]:=
Failure["InvalidRange",   <|
	"MessageTemplate" -> "Enter a number lower than `Number`", 
	"MessageParameters" -> <|"Number" -> 10|>
	|>]

Out[1]=
Failure["InvalidRange", Association["MessageTemplate" -> "Enter a number lower than `Number`", 
  "MessageParameters" -> Association["Number" -> 10]]]
```

### Scope (10)

#### Basic Uses (6)

Create a ``Failure`` using only a tag:

```wl
In[1]:= Failure["InvalidInput", <||>]

Out[1]= Failure["InvalidInput", Association[]]
```

---

Use a tag and a message:

```wl
In[1]:= Failure["InvalidInput", <|"Message" -> "Input must be a string"|>]

Out[1]= Failure["InvalidInput", Association["Message" -> "Input must be a string"]]
```

---

Use a template with positional parameters:

```wl
In[1]:= Failure["ExternalOperation", <|"MessageTemplate"  -> "External operation `1` failed.", "MessageParameters" -> { "file upload"}|>]

Out[1]=
Failure["ExternalOperation", Association["MessageTemplate" -> "External operation `1` failed.", 
  "MessageParameters" -> {"file upload"}]]
```

---

Indicate a failure using a ``StringTemplate`` :

```wl
In[1]:=
Failure["InvalidRange",   <|
	"MessageTemplate"  -> StringTemplate["Enter a number lower than `Number`"], 
	"MessageParameters" -> <|"Number" -> 10|>|>]

Out[1]=
Failure["InvalidRange", Association["MessageTemplate" -> 
   TemplateObject[{"Enter a number lower than ", TemplateSlot["Number"]}, 
    InsertionFunction -> TextString, CombinerFunction -> StringJoin], 
  "MessageParameters" -> Association["Number" -> 10]]]
```

---

Indicate a failure using ``MessageName`` :

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

Out[1]=
Failure["InvalidRange", Association["MessageTemplate" -> "Enter a number greater than `Number`", 
  "MessageParameters" -> Association["Number" -> 10]]]
```

---

``Failure`` can contain metadata:

```wl
In[1]:=
Failure["RestrictionFailure", 
	<|"MessageTemplate" :> Interpreter::numberinterval, 
	"MessageParameters" -> <|"Min" -> "1", "Max" -> "10", "Input" -> {"100"}|>, 
	"Interval" -> Interval[{1, 10}], 
	"Input" -> {"100"}, 
	"Type" -> "Number"|>
	]

Out[1]=
Failure["RestrictionFailure", Association["MessageTemplate" :> Interpreter::numberinterval, 
  "MessageParameters" -> Association["Min" -> "1", "Max" -> "10", "Input" -> {"100"}], 
  "Interval" -> Interval[{1, 10}], "Input" -> {"100"}, "Type" -> "Number"]]
```

#### Properties (4)

Get a list of all the available properties:

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

In[2]:= f["Properties"]

Out[2]= {"HeldMessageTemplate", "Input", "Interval", "Message", "MessageName", "MessageParameters", "MessageTemplate", "StyledMessage", "Type"}
```

Extract the ``"Input"`` property:

```wl
In[3]:= f["Input"]

Out[3]= {"100"}
```

---

Extract the message template, name and parameters:

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

In[2]:= f[{"MessageTemplate", "MessageName", "MessageParameters"}]

Out[2]= {"Enter a number between `Min` and `Max`.", Missing["NotAvailable", {"MessageTemplate", "MessageName", "MessageParameters"}], <|"Min" -> "1", "Max" -> "10", "Input" -> {"100"}|>}
```

---

Extract the message template without evaluating it:

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

In[2]:= f["HeldMessageTemplate"]

Out[2]= Hold[Interpreter::numberinterval]
```

---

Extract the actual error message:

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

In[2]:= f["Message"]

Out[2]= "Enter a number between 1 and 10."

In[3]:= f["StyledMessage"]

Out[3]= "Enter a number between 1 and 10."
```

### Properties & Relations (4)

Use ``ToString`` to get the formatted message:

```wl
In[1]:= f = Interpreter["Number"]["hello"];

In[2]:= f // ToString

Out[2]= "Enter a valid number."
```

This is equivalent to the ``"Message"`` property:

```wl
In[3]:= f["Message"]

Out[3]= "Enter a valid number."
```

---

``Failure`` is returned by functions like ``SendMail`` and ``EntityPrefetch`` :

```wl
In[1]:= EntityPrefetch["NoSuchEntity"]

Out[1]=
Failure["NoPrefetch", Association["MessageTemplate" :> 
   "Prefetch resources are unavailable for `type`.", "MessageParameters" -> 
   Association["type" -> "NoSuchEntity"], "Type" -> "NoSuchEntity", 
  "CloudBase" -> "https://www.wolframcloud.com/"]]
```

For these functions, the opposite of ``Failure`` is ``Success`` :

```wl
In[2]:= EntityPrefetch["Planet"]

Out[2]=
Success["Prefetch", Association["MessageTemplate" -> "Prefetch successful.", "Values" -> 664, 
  "Domain" -> "Planet", "CloudBase" -> "https://www.wolframcloud.com/"]]
```

---

``Failure`` expressions are ``FailureQ`` :

```wl
In[1]:=
FailureQ[Failure["InterpretationFailure", Association["MessageTemplate" :> Interpreter::number, 
  "MessageParameters" -> Association["Input" -> "notnumber"], "Input" -> "notnumber", 
  "Type" -> "Integer"]]]

Out[1]= True
```

---

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

```wl
In[1]:= MyFunc::nvldrange   = "Enter a number greater than `Number`";

In[2]:=
Failure["InvalidRange", <|"MessageTemplate" -> MyFunc::nvldrange|>];
%["HeldMessageTemplate"]

Out[2]= Hold["Enter a number greater than `Number`"]
```

Use ``RuleDelayed`` to prevent evaluation:

```wl
In[3]:=
Failure["InvalidRange", <|"MessageTemplate" :> MyFunc::nvldrange|>];
%["HeldMessageTemplate"]

Out[3]= Hold[MyFunc::nvldrange]
```

### Neat Examples (1)

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

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

In[2]:= AssociationMap[f, f["Properties"]]//Dataset

Out[2]= Dataset[<>]
```

## See Also

* [`Confirm`](https://reference.wolfram.com/language/ref/Confirm.en.md)
* [`Interpreter`](https://reference.wolfram.com/language/ref/Interpreter.en.md)
* [`\$Failed`](https://reference.wolfram.com/language/ref/$Failed.en.md)
* [`FailureQ`](https://reference.wolfram.com/language/ref/FailureQ.en.md)
* [`Message`](https://reference.wolfram.com/language/ref/Message.en.md)
* [`Success`](https://reference.wolfram.com/language/ref/Success.en.md)
* [`If`](https://reference.wolfram.com/language/ref/If.en.md)
* [`Assert`](https://reference.wolfram.com/language/ref/Assert.en.md)
* [`Missing`](https://reference.wolfram.com/language/ref/Missing.en.md)
* [`StringTemplate`](https://reference.wolfram.com/language/ref/StringTemplate.en.md)
* [`TerminatedEvaluation`](https://reference.wolfram.com/language/ref/TerminatedEvaluation.en.md)

## Related Guides

* [Creating Form Interfaces & Apps](https://reference.wolfram.com/language/guide/CreatingFormsAndApps.en.md)
* [Creating Instant APIs](https://reference.wolfram.com/language/guide/CreatingAnInstantAPI.en.md)
* [Package Development](https://reference.wolfram.com/language/guide/PackageDevelopment.en.md)
* [Setting Up Input Interpreters](https://reference.wolfram.com/language/guide/InterpretingStrings.en.md)
* [`Messages`](https://reference.wolfram.com/language/guide/Messages.en.md)
* [Free-Form & External Input](https://reference.wolfram.com/language/guide/FreeFormAndExternalInput.en.md)
* [Robustness & Error Handling](https://reference.wolfram.com/language/guide/RobustnessAndErrorHandling.en.md)
* [Automatic Mail Processing](https://reference.wolfram.com/language/guide/AutomaticMailProcessing.en.md)

## History

* [Introduced in 2014 (10.0)](https://reference.wolfram.com/language/guide/SummaryOfNewFeaturesIn100.en.md)