Edits

Author: bgribaudo

query-languages/m/m-spec-error-handling.md

@@ -2,7 +2,7 @@
 title: M Language Error Handling 
 description: Describes error handling in the Power Query M formula language
 ms.topic: language-reference
-ms.date: 8/2/2022
+ms.date: 1/29/26
 ms.custom: "nonautomated-date"
 ms.subservice: m-specification
 ---
@@ -24,29 +24,56 @@ The syntax for raising an error is as follows:
 _error-raising-expression:_<br/>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`error`  _expression_
 
-Text values can be used as shorthand for error values. For example:
+The _expression_ being raised must evaluate to an _error value_.
+
+In canonical form, an _error value_ is a record with the following structure:
 
 ```powerquery-m
-error "Hello, world" // error with message "Hello, world"
+[
+    ErrorCode = ...,
+    Reason = ...,
+    Message = ...,
+    Detail = ...,
+    Message.Format = ...,
+    Message.Parameters = ...
+]
 ```
 
-Full error values are records and can be constructed using the `Error.Record` function:
+All of the above record fields are optional, and so may be omitted or set to null. When not null, _Reason_, _Message_, and _Message.Format_ must be text, and _Message.Parameters_ must be a list. 
+
+Any additional fields included in the record will be ignored and so not included in the error that is raised.
+
+_Message.Format_ may contain string interpolation placeholders in the form of `#{x}`, where `x` is a zero-based index. When an error is raised with a non-null _Message.Foramt_, interpolation will be performed using _Message.Format_ as the format string and _Message.Parameters_ as the values to be positionally applied. The resulting output will become the raised error's _Message_.
+
+For example:
 
 ```powerquery-m
-error Error.Record("FileNotFound", "File my.txt not found",
-     "my.txt")
+error [
+    Message.Format = "Unexpected value '#{0}' in field #{1}", 
+    Message.Parameters = {"???", "Customer"}
+]
 ```
 
-The above expression is equivalent to:
+Will result in the following error being raised:
 
 ```powerquery-m
-error [ 
-    Reason = "FileNotFound", 
-    Message = "File my.txt not found", 
-    Detail = "my.txt" 
+[
+    ErrorCode = null,
+    Reason = null,
+    Message = "Unexpected value '???' in field Customer",
+    Detail = null,
+    Message.Format = "Unexpected value '#{0}' in field #{1}",
+    Message.Parameters = {"???", "Customer"}
 ]
 ```
 
+Text values can be used as shorthand for error values. For example:
+
+```powerquery-m
+error "Hello, world" // error with message "Hello, world"
+```
+
+
 Raising an error will cause the current expression evaluation to stop, and the expression evaluation stack will unwind until one of the following occurs:
 
 * A record field, section member, or let variable&mdash;collectively: an _entry_&mdash;is reached. The entry is marked as having an error, the error value is saved with that entry, and then propagated. Any subsequent access to that entry will cause an identical error to be raised. Other entries of the record, section, or let expression are not necessarily affected (unless they access an entry previously marked as having an error).