Errors And Diagnostics

In Grid, errors are first-class typed values. They flow through formulas just like numbers and strings, and you handle them with explicit error-handling functions and operators.

This doc lists every error code, when it fires, what it means, and how to recover.

1. The Error Value

Every error has:

• A code like VALUE, N/A, DIV/0, REF.
• A message explaining the cause.
• A typeTag of the form error:<code>.

In source code, 9 error literals are writable using the Excel-compatible spelling:

#N/A      #DIV/0!    #VALUE!    #REF!
#NAME?    #NULL!     #NUM!      #CALC!    #SPILL!

You can write any of these anywhere a value is expected:

A1 = #N/A
B1 = IF(missing, #N/A, value)

Two additional error codes are Grid-generated only — the parser rejects them as literals because they describe structural problems that source code shouldn't claim to produce:

If you need to construct one of these in a formula, use a function:

A1 = IF(condition, errorValue("TYPE", "..."), normalValue)   # not currently exposed

In v1, #TYPE! and #CIRCULAR_REF! are values you read, not values you write.

2. Every Error Code

Structured predicate fields are always enforced contracts. Unlike an ordinary type overlay under loose, predicate reviewed(score: number) cannot accept :reviewed("high"): field access and presence both surface #TYPE! so an invalid payload cannot be mistaken for a valid present predicate. Unknown predicate fields, wrong payload arity, and incomplete PREDICATES(x) views are compile-time diagnostics rather than error values. A many declaration must include a non-empty by (...) list of distinct declared fields. Adds require the complete payload; keyed removals require only the identity values, in many by order. Duplicate identity fields, unknown identity fields, and the wrong keyed-removal arity are also compile-time diagnostics.

Additional external-call failure codes may appear when a background value cannot be refreshed:

3. Error Propagation

Errors short-circuit. A function that receives an error argument returns that error unchanged unless it is one of the explicit error-handling functions or a structural predicate that is defined to inspect error identity.

A1 = #N/A
A2 = A1 + 5            # → #N/A (propagated)
A3 = SUM(A1, 1, 2)     # → #N/A (propagated)
A4 = IFERROR(A1, 0)    # → 0 (handled)
A5 = NA() IN [NA()]    # → TRUE (structural error-code comparison)
A6 = NA() IN [#VALUE!] # → FALSE (different error codes)

The first error encountered in a positional argument list wins. Named arguments don't change this rule for ordinary evaluation. IN/HAS, SUBSET/SUPERSET, OVERLAPS, and ordered CONTAINS are the collection relation exception: an error used as a member or pattern element is compared by error code, and its diagnostic message is ignored. They do not coerce the error into a normal scalar. Error-kind MATCH arms and the functions below are the other explicit inspection/handling forms.

4. Error-Handling Functions

These functions are designed to consume errors:

5. Error-Handling Operators And Clauses

5.1 DEFAULT / ??

The cheapest fallback. Returns the right-hand side if the left is BLANK or any error.

A1 DEFAULT 0          # canonical
A1 ?? 0               # accepted sugar

5.2 TRY ... ELSE

Inline form for guarding a single expression:

TRY 10 / 0 ELSE 0     # → 0

5.3 WITH ... THEN ... ELSE

For multi-step external chains where any step might fail:

WITH data = HTTP_JSON(url), users = data.results
THEN users[1].name ELSE "unavailable"

If HTTP_JSON fails, or data.results errors, or the then expression errors, the ELSE value is returned.

The bindings list can span lines (each , at end-of-line), but the final THEN <expr> ELSE <fallback> must be on a single line.

5.4 ASSERT Clause

Short-circuit a value through a predicate:

value ASSERT value > 0                    # #VALUE! if assertion fails
value ASSERT value > 0 ELSE #N/A          # custom error
score ASSERT score BETWEEN 0 AND 1

5.5 ?= (Conditional Eager Assignment)

If the right-hand side is any error, skip the assignment — preserve the previous value:

A3 = 0
A3 ?= MAYBE_FAIL()    # if MAYBE_FAIL() errors, A3 stays at 0

6. Validation Diagnostics

Some errors are model diagnostics rather than binding values. Grid reports them while parsing or validating the model.

A model with error-level validation diagnostics will not run. Fix all of them first.

6.1 Contextual grammar diagnostics

Some Grid forms are meaningful only in a particular grammatical context. A diagnostic for one of these forms is part of the language contract, not merely a parser failure. It identifies four things:

1. Attempted construct: the interpretation Grid gave the source.
2. Reason: why that construct cannot be used at this location.
3. Valid context: where the construct is accepted.
4. Canonical rewrite: a source form that expresses the supported shape.

For example, balance += payment at top level is recognized as arithmetic compound assignment. Grid explains that a top-level declaration has no prior value source, names a reactive rule action as the valid context, and shows the statement inside a WHEN ... THEN ... END rule. It does not report an unqualified "unexpected token" error.

Stable diagnostic codes let editors and agents act on the same contract:

6.2 Static-analysis diagnostics (warnings, strict-promoted)

Compile-time analyses emit these without running the model. All are warnings under the default mode; the first three become hard compile errors under strict / dimensions strict (see reference §5.4):

Anything the analyses cannot prove stays silent — unknown shapes and unbounded ranges never diagnose.

6.3 GRID_MIXED_OWNERSHIP (warning)

A binding has a plain formula and a set-mode rule action targeting it. The rule's write installs a sticky override that shadows the formula — the formula's value never surfaces once the rule first fires, and WHY would otherwise trace a formula whose value is dead.

B1 = A1 * 2                      # formula
WHEN tick THEN B1 = 99 END       # ⚠ GRID_MIXED_OWNERSHIP: the rule shadows B1's formula

This is a warning, not a blocking error — the model still runs (the override wins, as it does today). To resolve it:

• Mark the formula default if the override is intentional (the binding is a computed default a rule may override; RESET restores it), or
• move the rule off the binding if the formula should own it.

RESET and CLEAR actions never trigger the warning — they manage the override layer without colliding with the base op.

6.4 Symbolic-mathematics diagnostics

Symbolic mathematics fails closed at three boundaries. Source diagnostics reject an invalid declaration or lift before the model compiles; authority and compiled-model diagnostics reject unauthorized or malformed resident operations; mathematical operation records use :not_applicable, :limit, or :invalid without publishing an uncertified partial expression.

Common source diagnostics are:

The closed runtime family uses these stable diagnostic categories:

An expression-operation record with status = :limit or :invalid has expression = BLANK unless the operation explicitly defines a certified prefix. SYMBOLIC.SOLVE similarly keeps :none, :unknown, and :limit distinct. Do not recover from these states by parsing display text; inspect the status and conditions, reduce the problem or adjust the authored bound, and rerun the typed operation. See symbolic-mathematics.md.

7. The Error Type Tag

Every error value carries typeTag = "error:<code>". You can match on it explicitly:

A1 IS ERROR           # TRUE for any error
ISERR(A1)             # TRUE for any error other than #N/A

Format / display:

TEXT(A1, "")          # error string e.g. "#DIV/0!"

8. Worked Examples

8.1 Defensive Division

A1 = numerator
A2 = denominator
A3 = IFERROR(A1 / A2, 0)              # → 0 if A2 is 0

Or:

A3 = TRY A1 / A2 ELSE 0

Or:

A3 = A2 = 0 THEN 0 ELSE A1 / A2       # explicit guard

8.2 Lookup With Fallback

A1 = VLOOKUP("Alice", users, 2, FALSE) DEFAULT "n/a"
A2 = IFNA(VLOOKUP("Bob", users, 2, FALSE), "n/a")

8.3 External Call With Fallback

B1 = FX_RATE("EUR", "USD")
B2 is currency = ROUND(amount * (B1 DEFAULT 1.08), 2)

While B1 is queued or failed, B2 uses the fallback rate.

8.4 Multi-Step Chain

result = WITH data = HTTP_JSON(url), first = data.results[1], name = first.name
THEN name ELSE "unknown"

8.5 Validating An Input

A1 is percentage = input ASSERT input BETWEEN 0 AND 1 ELSE #VALUE!

8.6 Detecting Specific Errors

status = IF(ISNA(A1), "missing",
         IF(ISERR(A1), "error",
         IF(ISBLANK(A1), "empty", "ok")))

9. Common Mistakes

9.1 Forgetting Errors Propagate

A1 = SUM(B1:B10)         # B5 = #N/A → A1 = #N/A

If B1:B10 may contain errors, filter first:

A1 = SUM(IFERROR(B1:B10, 0))

Or use AGGREGATE with the "ignore errors" mode:

A1 = AGGREGATE(9, 6, B1:B10)

9.2 Confusing Blank With Empty String

A1 = ""                 # empty string, not blank
A2 = BLANK              # blank
ISBLANK(A1)             # FALSE
ISBLANK(A2)             # TRUE

9.3 Catching #N/A With ISERROR

ISERROR(#N/A)           # TRUE — catches everything
ISERR(#N/A)             # FALSE — explicitly excludes #N/A
ISNA(#N/A)              # TRUE — catches only #N/A

Use ISERR if you want "errors but not missing-values".

9.4 Treating External Pending States As Errors

A binding whose external call is queued or running is not an error. It carries a previous cached value (or BLANK) with a stale status. Use external-function status, not ISERROR, to distinguish pending work from failed work.

9.5 Using ?= On A Target That Doesn't Exist Yet

A1 ?= MAYBE_FAIL()      # if MAYBE_FAIL fails, A1 has no previous value to preserve → A1 stays uninitialized (BLANK)

?= only protects against overwriting; it doesn't conjure a value.

10. See Also

• reference.md for error literal spellings.
• functions.md for IFERROR, IFNA, etc.
• assignments.md for ?=.
• external-functions.md for status-vs-error distinction.