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.

Symbol requests also validate spreadsheet bounds. Letter-and-number names such as MdToM2 can be interpreted as addresses regardless of case. An out-of-range address error explains that ambiguity, states the supported bounds, and suggests an underscore such as Permeability_m2. This is a host symbol diagnostic, not a new formula error code. Valid A1/R1C1 references keep their meaning, and source names are not automatically rewritten.

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>.

CURVE_FIT and NSOLVE retain VALUE for malformed arguments and CALC for numerical failure, with a message identifying the function, cause, and recovery guidance. An underdetermined fit explains that there are more free parameters than observations. Initial-evaluation failure, singular numerical work, and nonconvergence have distinct explanations. See the chemistry workflow guide.

CURVE_FIT and PDE_SOLVE_1D messages also identify an explicit failure class, available argument/domain context or solver limit, and a recovery action. The Errors panel and cell inspector show those parts separately while preserving the existing error code and cell address. For example:

CURVE_FIT [iteration_limit_exceeded] (max_iter=1): The iteration budget was exhausted before a convergence criterion was met. Recovery: Review the initial guess, scaling, and tolerance; increase max_iter if the additional work is appropriate.

An initial evaluation failure means the model did not produce finite numeric values; it does not establish a particular mathematical cause. Known iteration or step exhaustion is distinguished from unspecified nonconvergence. PDE step underflow reports its stopping time without diagnosing a singularity. Fits with more than 64 coefficients now return CALC when their iteration budget is exhausted, rather than returning unconverged coefficients. Converged results retain their coefficient-only shape.

No known errors describes loaded results or the runtime's reported snapshot, as stated in the panel. It does not certify unresolved outputs. Saving or updating source is separate from successful calculation; observed calculation errors are reported separately without evaluating the whole model for a status badge.

Leading minus and powers

GRID_NEGATIVE_POWER_GROUPING is a nonfatal authoring warning with a line and column. Grid's existing precedence is unchanged: -2^2 means (-2)^2, giving 4. Write -(2^2) for -4. Both explicit forms are warning-free. The same rule applies to ** and named expressions: -(rate * time)^n still negates the base before raising it to a power. Write -((rate * time)^n) to negate the whole power, or give the positive exposure its own name and then negate that name. Grid does not choose an intention or rewrite source automatically.

Physical scale conflicts

GRID_UNIT_SCALE_MISMATCH identifies known representations that arithmetic does not normalize, such as kilometers and meters in 1km + 500m. Convert one operand explicitly before combining them. This warning preserves legacy numeric semantics; a physical tag is not a conversion. The independent unit_scales strict directive refuses reported conflicts and relevant unverified uses. Explicit unit_scales warn also reports GRID_UNIT_SCALE_UNVERIFIED for unsupported or dynamic contracts. Without a directive, only proven conflicts warn. off retains legacy inference. Unknown coverage is not proof of unit safety. See scale checking.

Scalar root recovery

Known native ROOT, FINDROOT, and GOALSEEK failures preserve their reason, available endpoint evidence, and recovery in Errors, Inspector, and I/O. NO_BRACKET asks the author to review the interval and branch; it does not claim the equation has no solution elsewhere. ARGUMENTS identifies invalid controls, EVALUATION a failed function evaluation, and ITERATION_LIMIT or BUDGET_EXHAUSTED exhausted work. Legacy or unknown messages remain visible without guessing a category. Use Find shared sources in Errors to inspect bounded upstream evidence; unavailable origins stay unknown.

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.

The subsections below explain the diagnostic families worth understanding in depth. The complete generated catalog of every GRID_* diagnostic code lives in diagnostics.md.

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 and IFNA, and functions.md#information for ISERROR, ISNA, and the other error inspectors.
• assignments.md for ?=.
• external-functions.md for status-vs-error distinction.

Address identity: GRID_ADDRESS_UNREPRESENTABLE

Grid rejects explicit A1/R1C1 source addresses outside columns A–XFC (1–16,383) and rows 1–67,108,863 before calculation. These are the coordinates whose identity the current address format can retain; views or imports may have lower limits. XFD is currently outside this range.

A descriptive name such as ContigN50 can match address syntax. Use Contig_N50 instead. The diagnostic includes the source location and naming hint. It does not rewrite existing archives or recover a value previously overwritten by a conflicting address. Review retained source when repairing an affected model.