Error Handling

onError

Type	(error: UpdogError) => void

Called when the SDK catches an internal error. The SDK recovers gracefully where possible — onError is for your logging and monitoring (Sentry, Datadog, etc.).

Error Shape

type UpdogError = {
  code: UpdogErrorCode;
  message: string;
  source: string;
  originalError?: unknown;
};

Error Codes

Code	When
PARSE_ERROR	File parsing failed (corrupt CSV, invalid XLSX, etc.)
RENDER_ERROR	Component render failed (caught by error boundary)
TRANSFORM_ERROR	Data transformation failed (column transform, value mapping)
VALIDATION_ERROR	Validation execution failed (validator threw instead of returning)
WORKER_ERROR	Web Worker failed (filter worker, chat transform worker)
COMMAND_ERROR	Undo/redo command failed
OPERATION_ERROR	General operation failed (bulk mutations, imports)

Example

onError={(error) => {
  Sentry.captureException(error.originalError ?? error, {
    tags: { code: error.code, source: error.source },
  });
}}

Async validation failures

Remote checks (unique.fn and { type: "asyncFunction" } validators) can fail in ways sync validation cannot. When a check throws, returns malformed data, or goes 60 seconds without any activity, the cells still awaiting a verdict become unverified: they are not marked invalid, and your backend should re-validate them at save time.

• A check failure (rejection or malformed result) is reported through onError as a VALIDATION_ERROR — once per sweep, not once per cell. A timeout is silent.
• Verdicts streamed via onChunk before a failure stay applied — a crash at 99% keeps the 99%.
• Do retries inside your fn; once it rejects, the SDK marks the remaining cells unverified and does not re-ask.

CSV parse warnings

Malformed rows in a CSV (for example, an unclosed quote) don’t fail the import. The file still parses and the rows enter the grid; the user sees a toast reporting how many rows had formatting issues and the first few affected row numbers. These warnings are informational and are not reported through onError. A hard parse failure still raises a PARSE_ERROR.