IngestX
Guides

Error Handling

Handling fatal and structural errors safely

Because IngestX relies on the browser's Promise architecture, it adheres to standard JavaScript try/catch workflows.

However, there is a fundamental distinction between catching a fatal error immediately, and inspecting row wise validation errors after an ingestion completes.

Catching Fatal Errors

When invoking ingestion.result, the Promise will reject if a fatal error occurs (such as a missing required header).

The recommended pattern is to try/catch the result resolution, and use the exported IngestionErrorType enum to determine exactly what went wrong.

import { ingest, IngestionErrorType } from "@izanagi-labs/ingestx";

try {
  const instance = ingest({ file, columns });
  const result = await instance.result;

  console.log("Success! File parsed without fatal errors.");
} catch (error: any) {
  // error is the rejected IngestionError

  if (error.type === IngestionErrorType.HEADER_MISMATCH) {
    console.error("Missing headers:", error.details.missing);
    alert(
      `Please fix your spreadsheet. We couldn't find: ${error.details.missing.join(", ")}`,
    );
  } else if (error.type === IngestionErrorType.COLLECTION_LIMIT_EXCEEDED) {
    alert("This file is too large for memory processing!");
  } else {
    console.error("The parser failed:", error.message);
  }
}

[!NOTE] When using the @izanagi-labs/ingestx/react useIngest hook, you don't need a try/catch for the ingestion result. The hook catches it internally and populates the reactive error state variable instead.

Row wise Validation Errors

Row level validation failures will not trigger a Promise rejection. The ingestion.result will resolve normally.

You must inspect the final payload to determine if any rows failed structural checks.

const result = await instance.result;

if (result.data.invalidRowsCount > 0) {
  // Some rows broke schema!

  result.data.errorsData.rowWiseErrors.forEach((err) => {
    console.warn(
      `Row ${err.rowIndex} failed on column '${err.columnKey}': ${err.errorMessage}`,
    );
  });
}

On this page