Improve type/snapshot error diagnostics with full path context (#570)

* Improve type/snapshot error diagnostics with full path context

* Add focused tests for snapshot/type diagnostics coverage

* Trim diagnostic coverage tests while keeping branch coverage

* update changelog

Author: xaviergonz

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+- `TypeCheckError` now supports a single object parameter and still accepts positional constructor arguments for backward compatibility.
+- `TypeCheckError.throw()` now throws `TypeCheckErrorFailure` (which extends `MobxKeystoneError`), and union snapshot mismatches now throw `SnapshotTypeMismatchError` (also extending `MobxKeystoneError`) with structured metadata.
+- Snapshot processing now throws a dedicated `SnapshotProcessingError` (extends `MobxKeystoneError`) across `fromSnapshot` / `applySnapshot` / reconciliation paths.
+- `SnapshotProcessingError` messages now include enriched diagnostics text (full deep path, value preview, and model trail when available), making it much easier to pinpoint failing nested fields quickly.
+- `SnapshotProcessingError`, `SnapshotTypeMismatchError`, and `TypeCheckError` now share one diagnostics message formatter and a consistent layout: `MSG - Path: ... - Value: ... - Model trail: ...`, so error output is predictable across snapshot and type-check flows.
+- Improved snapshot/type error diagnostics end-to-end: path-aware messages across `fromSnapshot` / `applySnapshot` / union snapshot processing, plus structured error metadata (`path`, `expectedTypeName`, `actualValue`, `typeCheckedValue`, `modelTrail`) on thrown errors when available for easier tooling and debugging.
+- Note: because diagnostics were improved, error message text changed in these paths (`TypeCheckError`, `SnapshotProcessingError`, `SnapshotTypeMismatchError`, and related snapshot/apply patches flows). If you assert exact error strings, update expectations.
+- `applyPatches` reconciliation errors now also include accurate patch paths in diagnostics.
+
 ## 1.13.0
 
 - Added array syntax as a `tProp` union shorthand, for example `tProp([String, Number])` as an alias for `tProp(types.or(String, Number))`.

apps/site/docs/runtimeTypeChecking.mdx

@@ -62,7 +62,11 @@ In all cases the returned value will be `null` if there are no errors or an inst
 - `path: Path` - Sub-path where the type-check failed, or an empty array if the actual object/value failed the type-check.
 - `expectedTypeName: string` - String representation of the expected type.
 - `actualValue: any` - The actual value/sub-value that failed the type-check
-- `throw(typeCheckedValue: any)` - Throws the error as an exception.
+- `typeCheckedValue?: any` - The value/object where the type-check was invoked.
+- `modelTrail?: readonly string[]` - Optional model/type trail (for example during snapshot processing of nested models).
+- `throw()` - Throws a `TypeCheckErrorFailure` as an exception.
+
+`TypeCheckErrorFailure` extends `MobxKeystoneError`, so `instanceof MobxKeystoneError` checks work on thrown failures.
 
 While models are usually automatically type-checked, it is worth noting that other values (primitives, plain objects, arrays) are not until they become attached to some model. If you need to type-check those before they become attached to a model it is always possible to use `typeCheck(type, value)` as shown previously to trigger a manual validation.
 
@@ -139,6 +143,7 @@ const shapeType = types.or(
 ```
 
 The dispatcher receives the snapshot and must return one of the provided union types.
+When no union branch matches during snapshot conversion, `types.or` throws `SnapshotTypeMismatchError` (a `MobxKeystoneError`) with path/type/value metadata.
 
 ### `types.maybe(type)`
 
@@ -290,7 +295,13 @@ const sumModelType = types.refinement(types.model(Sum), (sum) => {
   return rightResult
 
   // this will return that the result field is wrong
-  return rightResult ? null : new TypeCheckError(["result"], "a+b", sum.result)
+  return rightResult
+    ? null
+    : new TypeCheckError({
+        path: ["result"],
+        expectedTypeName: "a+b",
+        actualValue: sum.result,
+      })
 })
 ```
 

apps/site/docs/snapshots.mdx

@@ -194,6 +194,8 @@ applySnapshot(todo, {
 
 In the case above, only a single patch will be generated (for the `done` property), and the same todo instance will be reused (since they have the same model ID).
 
+When `fromSnapshot` or `applySnapshot` fails due to snapshot processing issues, it throws `SnapshotProcessingError` (extends `MobxKeystoneError`) and includes diagnostic metadata such as `path`, `actualSnapshot` (when available), and `modelTrail` (when available). Its error message is also enriched with this metadata (plus a safe value preview when available).
+
 ## Cloning via snapshots
 
 ### `clone`

packages/lib/src/modelShared/sharedInternalModel.ts

@@ -15,6 +15,7 @@ import type { AnyType } from "../types/schemas"
 import { tProp } from "../types/tProp"
 import type { LateTypeChecker } from "../types/TypeChecker"
 import { typesUnchecked } from "../types/utility/typesUnchecked"
+import { withErrorPathSegment } from "../utils/errorDiagnostics"
 import { addHiddenProp, assertIsObject, failure, propNameToSetterName } from "../utils"
 import { chainFns } from "../utils/chainFns"
 import { ModelClass, modelInitializedSymbol } from "./BaseModelShared"
@@ -75,7 +76,9 @@ const setModelInstanceDataField: SetModelInstanceDataFieldFn = (
   }
 
   let untransformedValue = modelProp._transform
-    ? modelProp._transform.untransform(value, model, modelPropName)
+    ? withErrorPathSegment(modelPropName, () =>
+        modelProp._transform!.untransform(value, model, modelPropName)
+      )
     : value
 
   // apply default value if applicable
@@ -354,7 +357,9 @@ function getModelPropsFromSnapshotProcessor(
     const newSn = { ...sn }
     for (const [propName, propData] of propsWithFromSnapshotProcessor) {
       if (propData._fromSnapshotProcessor) {
-        newSn[propName] = propData._fromSnapshotProcessor(sn[propName])
+        newSn[propName] = withErrorPathSegment(propName, () =>
+          propData._fromSnapshotProcessor!(sn[propName])
+        )
       }
     }
     return newSn
@@ -376,7 +381,7 @@ function getModelPropsToSnapshotProcessor(
     const newSn = { ...sn }
     for (const [propName, propData] of propsWithToSnapshotProcessor) {
       if (propData._toSnapshotProcessor) {
-        newSn[propName] = propData._toSnapshotProcessor(sn[propName])
+        newSn[propName] = withErrorPathSegment(propName, () => propData._toSnapshotProcessor!(sn[propName]))
       }
     }
     return newSn

packages/lib/src/patch/applyPatches.ts

@@ -8,6 +8,7 @@ import type { Patch } from "../patch/Patch"
 import { reconcileSnapshot } from "../snapshot/reconcileSnapshot"
 import { assertTweakedObject } from "../tweaker/core"
 import { failure, inDevMode, isArray, lazy } from "../utils"
+import { runWithErrorDiagnosticsContext, withErrorPathSegments } from "../utils/errorDiagnostics"
 import { ModelPool } from "../utils/ModelPool"
 import { setIfDifferent } from "../utils/setIfDifferent"
 
@@ -40,36 +41,38 @@ export function internalApplyPatches(
   patches: ReadonlyArray<Patch> | ReadonlyArray<ReadonlyArray<Patch>>,
   reverse = false
 ): void {
-  const obj = this
-  const modelPool = new ModelPool(obj)
-
-  if (reverse) {
-    let i = patches.length
-    while (i--) {
-      const p = patches[i]
-      if (isArray(p)) {
-        let j = p.length
-        while (j--) {
-          applySinglePatch(obj, p[j], modelPool)
+  runWithErrorDiagnosticsContext(() => {
+    const obj = this
+    const modelPool = new ModelPool(obj)
+
+    if (reverse) {
+      let i = patches.length
+      while (i--) {
+        const p = patches[i]
+        if (isArray(p)) {
+          let j = p.length
+          while (j--) {
+            applySinglePatchWithPath(obj, p[j], modelPool)
+          }
+        } else {
+          applySinglePatchWithPath(obj, p as Patch, modelPool)
         }
-      } else {
-        applySinglePatch(obj, p as Patch, modelPool)
       }
-    }
-  } else {
-    const len = patches.length
-    for (let i = 0; i < len; i++) {
-      const p = patches[i]
-      if (isArray(p)) {
-        const len2 = p.length
-        for (let j = 0; j < len2; j++) {
-          applySinglePatch(obj, p[j], modelPool)
+    } else {
+      const len = patches.length
+      for (let i = 0; i < len; i++) {
+        const p = patches[i]
+        if (isArray(p)) {
+          const len2 = p.length
+          for (let j = 0; j < len2; j++) {
+            applySinglePatchWithPath(obj, p[j], modelPool)
+          }
+        } else {
+          applySinglePatchWithPath(obj, p as Patch, modelPool)
         }
-      } else {
-        applySinglePatch(obj, p as Patch, modelPool)
       }
     }
-  }
+  })
 }
 
 const wrappedInternalApplyPatches = lazy(() =>
@@ -149,6 +152,12 @@ function applySinglePatch(obj: object, patch: Patch, modelPool: ModelPool): void
   }
 }
 
+function applySinglePatchWithPath(obj: object, patch: Patch, modelPool: ModelPool): void {
+  withErrorPathSegments(patch.path, () => {
+    applySinglePatch(obj, patch, modelPool)
+  })
+}
+
 function pathArrayToObjectAndProp(
   obj: object,
   path: Patch["path"]

packages/lib/src/snapshot/SnapshotProcessingError.ts

@@ -0,0 +1,45 @@
+import { Path } from "../parent/pathTypes"
+import { MobxKeystoneError } from "../utils"
+import {
+  buildErrorMessageWithDiagnostics,
+  getErrorModelTrailSnapshot,
+  getErrorPathSnapshot,
+  noErrorValuePreview,
+} from "../utils/errorDiagnostics"
+
+export interface SnapshotProcessingErrorData {
+  message: string
+  path?: Path
+  actualSnapshot?: any
+  modelTrail?: readonly string[]
+}
+
+/**
+ * Thrown when a structural issue is encountered while processing a snapshot (extends `MobxKeystoneError`).
+ *
+ * Use `instanceof SnapshotProcessingError` to distinguish snapshot processing errors
+ * from other `MobxKeystoneError` instances.
+ */
+export class SnapshotProcessingError extends MobxKeystoneError {
+  readonly path: Path
+  readonly actualSnapshot?: any
+  readonly modelTrail?: readonly string[]
+
+  constructor(data: SnapshotProcessingErrorData) {
+    const path = data.path ?? getErrorPathSnapshot() ?? []
+    const modelTrail = data.modelTrail ?? getErrorModelTrailSnapshot()
+
+    super(
+      buildErrorMessageWithDiagnostics({
+        message: data.message,
+        path,
+        previewValue: "actualSnapshot" in data ? data.actualSnapshot : noErrorValuePreview,
+        modelTrail,
+      })
+    )
+
+    this.path = path
+    this.actualSnapshot = data.actualSnapshot
+    this.modelTrail = modelTrail
+  }
+}

packages/lib/src/snapshot/applySnapshot.ts

@@ -10,19 +10,14 @@ import { getSnapshotModelType, isModel } from "../model/utils"
 import type { ModelClass } from "../modelShared/BaseModelShared"
 import { getModelInfoForName, modelInfoByClass } from "../modelShared/modelInfo"
 import { assertTweakedObject } from "../tweaker/core"
+import { assertIsObject, inDevMode, isArray, isMap, isPlainObject, isSet, lazy } from "../utils"
 import {
-  assertIsObject,
-  failure,
-  inDevMode,
-  isArray,
-  isMap,
-  isPlainObject,
-  isSet,
-  lazy,
-} from "../utils"
+  runWithErrorDiagnosticsContext,
+} from "../utils/errorDiagnostics"
 import { ModelPool } from "../utils/ModelPool"
 import { reconcileSnapshot } from "./reconcileSnapshot"
 import type { SnapshotInOf, SnapshotOutOf } from "./SnapshotOf"
+import { SnapshotProcessingError } from "./SnapshotProcessingError"
 
 /**
  * Applies a full snapshot over an object, reconciling it with the current contents of the object.
@@ -40,7 +35,9 @@ export function applySnapshot(node: object, snapshot: unknown): void {
   assertTweakedObject(node, "node")
   assertIsObject(snapshot, "snapshot")
 
-  wrappedInternalApplySnapshot().call(node, snapshot)
+  runWithErrorDiagnosticsContext(() => {
+    wrappedInternalApplySnapshot().call(node, snapshot)
+  })
 }
 
 /**
@@ -58,22 +55,31 @@ export function internalApplySnapshot<T extends object>(
 
     if (inDevMode) {
       if (ret !== obj) {
-        throw failure("assertion failed: reconciled object has to be the same")
+        throw new SnapshotProcessingError({
+          message: "assertion failed: reconciled object has to be the same",
+          actualSnapshot: sn,
+        })
       }
     }
   }
 
   if (isArray(sn)) {
     if (!isArray(obj)) {
-      throw failure("if the snapshot is an array the target must be an array too")
+      throw new SnapshotProcessingError({
+        message: "if the snapshot is an array the target must be an array too",
+        actualSnapshot: sn,
+      })
     }
 
     reconcile()
     return
   }
 
   if (isFrozenSnapshot(sn)) {
-    throw failure("applySnapshot cannot be used over frozen objects")
+    throw new SnapshotProcessingError({
+      message: "applySnapshot cannot be used over frozen objects",
+      actualSnapshot: sn,
+    })
   }
 
   // adapt snapshot to target model if possible
@@ -86,32 +92,42 @@ export function internalApplySnapshot<T extends object>(
   if (modelType !== undefined) {
     const modelInfo = getModelInfoForName(modelType)
     if (!modelInfo) {
-      throw failure(`model with name "${modelType}" not found in the registry`)
+      throw new SnapshotProcessingError({
+        message: `model with name "${modelType}" not found in the registry`,
+        actualSnapshot: sn,
+      })
     }
 
     // we don't check by actual instance since the class might be a different one due to hot reloading
     if (!isModel(obj)) {
       // not a model instance, no reconciliation possible
-      throw failure(`the target for a model snapshot must be a model instance`)
+      throw new SnapshotProcessingError({
+        message: "the target for a model snapshot must be a model instance",
+        actualSnapshot: sn,
+      })
     }
 
     if (obj[modelTypeKey] !== modelType) {
       // different kind of model, no reconciliation possible
-      throw failure(
-        `snapshot model type '${modelType}' does not match target model type '${
+      throw new SnapshotProcessingError({
+        message: `snapshot model type '${modelType}' does not match target model type '${
           (obj as any)[modelTypeKey]
-        }'`
-      )
+        }'`,
+        actualSnapshot: sn,
+      })
     }
 
     const modelIdPropertyName = getModelIdPropertyName(modelInfo.class as ModelClass<AnyModel>)
     if (modelIdPropertyName) {
       const id = (sn as any)[modelIdPropertyName]
       if (obj[modelIdKey] !== id) {
         // different id, no reconciliation possible
-        throw failure(
-          `snapshot model id '${id}' does not match target model id '${obj[modelIdKey]}'`
-        )
+        throw new SnapshotProcessingError({
+          message: `snapshot model id '${id}' does not match target model id '${
+            obj[modelIdKey]
+          }'`,
+          actualSnapshot: sn,
+        })
       }
     }
 
@@ -122,22 +138,34 @@ export function internalApplySnapshot<T extends object>(
   if (isPlainObject(sn)) {
     if (!(isPlainObject(obj) || isObservableObject(obj))) {
       // no reconciliation possible
-      throw failure("if the snapshot is an object the target must be an object too")
+      throw new SnapshotProcessingError({
+        message: "if the snapshot is an object the target must be an object too",
+        actualSnapshot: sn,
+      })
     }
 
     reconcile()
     return
   }
 
   if (isMap(sn)) {
-    throw failure("a snapshot must not contain maps")
+    throw new SnapshotProcessingError({
+      message: "a snapshot must not contain maps",
+      actualSnapshot: sn,
+    })
   }
 
   if (isSet(sn)) {
-    throw failure("a snapshot must not contain sets")
+    throw new SnapshotProcessingError({
+      message: "a snapshot must not contain sets",
+      actualSnapshot: sn,
+    })
   }
 
-  throw failure(`unsupported snapshot - ${sn}`)
+  throw new SnapshotProcessingError({
+    message: "unsupported snapshot",
+    actualSnapshot: sn,
+  })
 }
 
 const wrappedInternalApplySnapshot = lazy(() =>