# X12 Mapper error codes

Generated from `MapperErrorCode.java` during the X12 Maven build. Do not edit this file by hand.

Each entry describes a stable core DSL code, its meaning, and a suggested correction.
The actual diagnostic adds the relevant source location and input-specific details.
This catalog covers syntax, validation, runtime, and built-in function codes; it does not
describe X12 interchange validation codes, host/API failures, or custom function libraries.
Validation can detect some failures before execution; other failures depend on input data.
Read the function label for codes with more than one existing use, especially `E2801`.

| Code | Area | Meaning | What to do |
| --- | --- | --- | --- |
| `E1000` | Syntax | The source contains invalid or incomplete syntax. | Check the indicated token, separators, and numeric literals. Use integers without extra leading zeros or decimals with one decimal point. |
| `E1001` | Syntax | An element selector has a missing or malformed position. | Use a 1-based position such as ST(01) or ST->N1(02). Separate composite positions with a colon, as in ST->N9(07:02), not a decimal point. |
| `E1002` | Syntax | A closing parenthesis, bracket, or brace is missing. | Close the function call, expression, list, dictionary, or block before the next statement. |
| `E1101` | Syntax | A dictionary entry is missing its value after the colon. | Supply both parts of each key:value entry, for example {"a":"x"}. |
| `E1201` | Syntax | A list literal has a missing item between commas. | Remove the extra comma or supply a value, for example [1,2] or [1,"",2]. |
| `E1301` | Syntax | A forEach dictionary projection is missing its value after the colon. | Use a complete key:value projection, for example forEach(x in ST->N1 => x(01):x(02)). |
| `E1401` | Variables and types | A referenced variable is not in scope. | Define it before use and check the available names in the diagnostic. Loop variables are available only inside their loop. |
| `E1402` | Variables and types | A value is in scope but has the wrong type for the operation. | Use a list or dictionary where a collection is required: trim(" A ") returns a string, while trim([" A "]) returns a list. A segment selection is iterable but is not a mutable list; project a list with forEach before add, set, or indexing. key/val require a supported collection binding. |
| `E1501` | Assignment | A compound assignment targets an uninitialized or non-assignable variable. | Initialize a separate user variable first, for example total = 0, then total += 1. Do not use compound assignment on an iterating segment binding. |
| `E1502` | Assignment | A compound numeric assignment targets a non-numeric value. | Assign a number or explicitly convert numeric text with toNumber before applying the compound operator. |
| `E1601` | X12 paths | A segment path does not follow the transaction set's immediate-child structure. | Start from ST or a segment variable and follow the available child segments listed in the diagnostic. Check the selected X12 version and transaction set. |
| `E1602` | X12 paths | The logical HL descendant operator is used with an invalid source or target. | Use >> HL from ST or an HL segment to follow HL01/HL02 parent links. Use -> for ordinary transaction-set structure navigation. |
| `E1701` | X12 elements | An element or sub-element position is outside its valid range. | Use the segment's 1-based element range and the composite's valid sub-element range. Start at 01, not 00. |
| `E1702` | X12 elements | A direct segment element selector does not target the root ST segment. | Use ST(n), a segment loop variable such as line(n), or a path starting at ST such as ST->N1(n). |
| `E1703` | X12 elements | An element selector or predicate has a missing or invalid position. | Supply a valid 1-based position, for example ST(01), ST->N1(02), or ST->N1[01 == "ST"]. |
| `E1704` | X12 elements | A sub-element was selected from an element that is not composite. | Select the whole element without a colon, or choose a composite element from the X12 reference. |
| `E1801` | Variables and types | A named string constant is unknown. | Choose one of the available constants in the diagnostic, or use a quoted string literal for plain text. |
| `E1901` | Functions | The function name is unknown. | Check its spelling against the function reference. An embedded custom function must be registered in the FunctionRegistry. |
| `E1902` | Functions | The function was called with an incorrect argument count. | Match the required and optional arguments in the function signature. |
| `E2001` | X12 conversion | decodeId expected an X12 identifier element. | Select an ID-typed element whose code list should be decoded; do not pass ordinary text or another element type. |
| `E2002` | X12 conversion | A selected X12 date element is empty in isoLocalDate. | Supply a date or guard the conversion with isEmpty(...). |
| `E2003` | X12 conversion | A selected X12 date element is empty in unixTime. | Supply a date or guard the conversion with isEmpty(...). |
| `E2004` | X12 conversion | A selected X12 time element is empty in unixTime. | Supply a time or guard the conversion with isEmpty(...). |
| `E2101` | Lists | A list read uses an index outside the list's bounds. | Use a zero-based index below the list length and check for an empty list before indexing. |
| `E2102` | Lists | A list assignment uses an index outside the existing list. | Replace an existing zero-based position. Use add(list, value) to append a new item. |
| `E2103` | Lists | A list index is not a supported non-negative integer. | Supply a numeric index such as 0, 1, or 2 within the supported integer range; do not use text or a negative value. |
| `E2104` | Lists | A list index has a fractional value. | Supply a whole-number index rather than a fractional decimal. |
| `E2201` | Collection projections | A dictionary assignment uses a forEach without a dictionary projection. | Use => with key:value, for example forEach(x in ST->N1 => x(01):x(02)). |
| `E2202` | Collection projections | A list assignment uses a forEach without a value projection. | Use => with a value, for example forEach(x in ST->N1 => x(02)). |
| `E2301` | Dictionaries | A dictionary key is a collection rather than a scalar value. | Use a scalar key such as "sku" or 1; project a single value from a collection first. |
| `E2302` | Dictionaries | key cannot read an entry from an empty dictionary. | Guard an empty dictionary or call key inside a loop over its entries. |
| `E2303` | Dictionaries | val cannot read an entry from an empty dictionary. | Guard an empty dictionary or call val inside a loop over its entries. |
| `E2304` | Dictionaries | A nested assignment traverses a dictionary key that does not exist. | Initialize intermediate dictionaries before assigning through their keys. |
| `E2305` | Dictionaries | A nested assignment traverses or indexes a value that is neither a dictionary nor a list. | Initialize the intermediate value as the intended collection before assigning through it. |
| `E2306` | Dictionaries | An assignment through an iterating dictionary entry targets a different key. | Replace the current entry's value using its existing key, or update the owning dictionary explicitly. |
| `E2401` | Numbers and conditions | A variable cannot be converted to a number in an arithmetic context. | Assign a numeric value or use toNumber on a supported single numeric value before arithmetic. |
| `E2402` | Numbers and conditions | An expression or aggregate projection cannot be converted to a number. | Select or produce a numeric value. Check empty selections and find results before using them in arithmetic or sumOf. |
| `E2501` | Numbers and conditions | An expression is not a segment-element source. | For an element selector, use ST, an X12 path, or a segment binding rather than an ordinary function result. |
| `E2502` | Numbers and conditions | A relational comparison requires numeric operands. | Use == or != to compare text, or toNumber(...) to explicitly convert numeric text before ordering it. |
| `E2503` | Numbers and conditions | An arrow-filter relational comparison has non-numeric operands. | Use ==, !=, %==, or %!= for string qualifiers. Use numeric values for <, >, <=, and >=. |
| `E2504` | Numbers and conditions | A condition requires a boolean but received another type. | Use a comparison or a boolean result. Strings, numbers, and collections are not implicitly true or false. |
| `E2601` | Selection and cardinality | find matched more than one item. | Tighten the predicate or use a collection-returning construct when several matches are valid. |
| `E2602` | Selection and cardinality | find matched no item and has no default value. | Provide a default or widen the predicate if absence is valid; otherwise correct the input. |
| `E2603` | Selection and cardinality | find encountered an unsupported matched value type. | Use supported mapper values in the source collection. If ordinary DSL values trigger this, retain the mapping and input as a reproducible defect. |
| `E2604` | Selection and cardinality | A segment selection violates its !, ?, or + cardinality assertion. | Use ! for exactly one, ? for zero or one, and + for at least one match. Tighten the predicate or change/remove the assertion when that multiplicity is intentional. |
| `E2701` | Qualifier helpers | More than one segment was supplied to a single-segment helper. | Use a loop variable or select a single segment before reading its qualifier/value pairs. |
| `E2702` | Qualifier helpers | The first argument is not a segment or segment selection. | Use qualifierValue(ST->PO1!, "UP", 6), not qualifierValue("PO1", "UP", 6). Index an ordinary list to select its segment first. |
| `E2703` | Qualifier helpers | The required qualifier is missing. | Supply the qualifier or use qualifierValue(...) for optional data. |
| `E2704` | Qualifier helpers | The qualifier occurs more than once in the segment. | Correct duplicate source pairs or select an explicit element position. |
| `E2705` | Qualifier helpers | The required segment argument is empty. | Supply a segment or use qualifierValue(...) for optional data. |
| `E2706` | Qualifier helpers | The matched qualifier has no paired value element beside it. | Correct the first qualifier position or supply the paired element. |
| `E2707` | Qualifier helpers | firstQualifierElement is not a positive whole 32-bit integer. | Supply the 1-based position of the first qualifier, for example 6 for PO1 qualifier/value pairs. |
| `E2801` | Required values and aggregates | required received an empty value, or an aggregate source has an unsupported type. This code has two existing meanings. | Read the diagnostic's function label: for required, supply a non-empty value; for aggregate, use a segment path, element selection, list, or dictionary. |
| `E2802` | Collection projections | A flatMap projection does not return a list. | Return a list such as [item], an element selection, or a mapped forEach list. A segment selection is not a projected list. |
| `E2901` | Date formatting | The input date cannot be parsed by formatDate. | Supply a supported basic or ISO date, or an X12 date element. |
| `E2902` | Date formatting | A selected X12 date element is empty in formatDate. | Supply a date or guard the conversion with isEmpty(...). |
| `E2903` | Date formatting | The formatter pattern is invalid. | Use a valid date formatter pattern, for example yyyy-MM-dd, and check literal quoting. |
| `E2904` | Date formatting | The selected X12 element is not a date. | Select a date field or pass supported date text instead. |
| `E2905` | Date formatting | The output pattern requests fields unavailable in a date. | Remove time-of-day or other unsupported fields from the pattern. |
| `E3001` | Expression mode | Expression validation requires exactly one value-returning expression. | Provide one expression without assignments or statement blocks. Use program mode for a full mapping. |
| `E3101` | UPC-A | A code contains a character other than ASCII 0-9. | Supply digits only, without spaces, signs, or separators. |
| `E3102` | UPC-A | A code is neither 11 nor 12 characters long. | Supply an 11-digit body or a complete 12-digit UPC-A code. |
| `E3103` | UPC-A | The existing check digit does not match the first 11 digits. | Correct the source UPC-A code; the function does not replace an incorrect digit. |
| `E3104` | UPC-A | The argument is not a list of alphanumeric X12 elements. | Pass an element selection such as ST->PO1(07). Scalar values and lists of strings are not accepted. |
| `E3201` | Text | A list item is neither text nor an X12 element. | Supply a flat list of text values or an X12 element selection. |
| `E3202` | Text | The first argument is neither a string nor a list. | Supply text, for example "abc", a text list, or an X12 element selection. |
| `E3203` | Text | An index is not a populated whole 32-bit integer. | Supply a whole-number index in the supported range. |
| `E3204` | Text | An index or range is outside an input item's bounds. | Check every item's length and keep the start at or before the end. |
| `E3205` | Text | A segment selection was supplied where text or elements are required. | Select elements, for example join(ST->PO1(07), ","), or explicitly project text first. |
| `E3301` | Lists | join received a first argument that is not a list. | Supply a list of values or an element selection. |
| `E3302` | Lists | join received a collection as its separator. | Supply a scalar separator such as ",". |
| `E3401` | Rounding | The value cannot be converted to a populated number. | Supply a number, numeric text, or one populated numeric element before rounding. |
| `E3402` | Rounding | The scale is not a populated whole 32-bit integer. | Supply an integer scale such as 2 for cents or -1 for tens. |
| `E3403` | Rounding | The requested decimal scale cannot be represented. | Choose a practical scale supported by decimal arithmetic. |
| `E3501` | Dictionaries | containsKey received a first argument that is not a dictionary. | Supply a dictionary and the scalar key to look up. |
| `E3601` | Structured output | xml received a collection as its tag name. | Supply a scalar tag name, for example xml("item", value). |
| `E3701` | X12 conversion | decodeId received an argument that is not a list. | Pass an X12 identifier element selection. |
| `E3702` | X12 conversion | A decodeId list item is not an X12 element. | Select identifier elements instead of passing ordinary strings. |
| `E3801` | X12 conversion | isoLocalDate received an argument that is not a list. | Pass an X12 date element selection. |
| `E3802` | X12 conversion | An isoLocalDate list item is not an X12 date element. | Select a date field; use formatDate(...) for text dates. |
| `E3901` | X12 conversion | A unixTime argument is not a list of X12 elements. | Pass paired X12 date and time element selections. |
| `E3902` | X12 conversion | The date and time lists have different lengths. | Select one time value for each date value. |
| `E3903` | X12 conversion | A date-list element has the wrong X12 type. | Pass date elements as the first unixTime argument. |
| `E3904` | X12 conversion | A time-list element has the wrong X12 type. | Pass time elements as the second unixTime argument. |
| `E4001` | Location helpers | A toLatLong argument is not a list of X12 elements. | Select paired location identifier and qualifier elements. |
| `E4002` | Location helpers | The location identifier and qualifier lists have different lengths. | Select one qualifier for each location identifier. |
| `E4003` | Location helpers | A location qualifier is not an identifier element with definition 309. | Pass the X12 Location Qualifier element as the second toLatLong argument. |
| `E4101` | ISO 6346 | An argument is not a list of alphanumeric X12 elements. | Select the equipment initial and number elements. |
| `E4102` | ISO 6346 | The equipment initial and number lists have different lengths. | Select one equipment number for each initial. |
| `E4103` | ISO 6346 | The element definitions are not 206 and 207. | Pass Equipment Initial first and Equipment Number second. |
| `E4104` | ISO 6346 | The combined identifier is neither 10 nor 11 characters long. | Supply the 10-character body with an optional check digit. |
| `E4105` | ISO 6346 | The body contains a character outside A-Z and 0-9. | Supply uppercase letters and digits without spaces or punctuation. |
| `E4201` | ISO 6346 | decodeIso6346 received an argument that is not a list. | Pass an X12 equipment-type element selection. |
| `E4202` | ISO 6346 | A decodeIso6346 list item is not an X12 identifier element. | Select an ID-typed equipment-type element. |
| `E4203` | ISO 6346 | The selected element does not have definition 24. | Select Equipment Type (element 24) before decoding. |
| `E4301` | Structured output | A list or dictionary refers back to itself during toJson serialization. | Remove the circular reference. Reusing the same collection in separate branches is allowed. |
| `E4401` | Structured output | A list or dictionary refers back to itself during set conversion. | Remove the circular reference before converting to a set. |
| `E4501` | X12 conversion | The identifier definition is not a populated whole 32-bit integer. | Supply an integer X12 identifier definition number. |
| `E4601` | Number conversion | The value is not a supported number or numeric text. | For example, toNumber("EA") fails; provide a numeric value instead. |
| `E4602` | Number conversion | The value or selection is empty. | Guard missing data or explicitly supply a default, for example toNumber(firstNonEmpty([], "0")). |
| `E4603` | Number conversion | More than one value was supplied. | Select one item, project each item with forEach, or aggregate the collection before conversion. |
| `E4701` | Ordering | The sorting key is not a number, text, or single X12 element. | Project one scalar key, for example orderBy(n in [1] => n), rather than => [n]. |
| `E4702` | Ordering | Numeric and text keys are mixed in one sort. | Use one key type throughout; for numeric order, explicitly convert numeric text with toNumber. |
| `E4703` | Ordering | The direction is not the string "asc" or "desc". | Choose "asc" for ascending or "desc" for descending order. |
| `E4801` | Splitting text | The input is not text or a single text/X12 element. | For example, split(123, ",") fails; use split("123", ",") for text. |
| `E4802` | Splitting text | An input list or selection contains zero or multiple values. | Use forEach or flatMap to split each input explicitly, or select one populated item. |
| `E4803` | Splitting text | The separator is empty or is not a string. | Use a non-empty literal separator, for example split("A,B", ","). |