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/reactuseIngesthook, you don't need atry/catchfor the ingestion result. The hook catches it internally and populates the reactiveerrorstate 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}`,
);
});
}