Option on_skip

The on_skip option provides a way to track invalid records without interrupting the parsing process. It defines a function called when records are skipped due to parsing errors.

• Type: function
• Optional
• Default: undefined
• Since: 5.1.0
• Related: on_record, skip_records_with_error, raw — see Available Options

The on_skip option works at the record level and requires the skip_records_with_error option to be enabled.

Use cases

Use this option to:

• Log skipped records for later analysis
• Track parsing errors while maintaining the parsing process
• Monitor data quality issues in your CSV files

Usage

The user function receives the error object as an argument. If the raw option is enabled, a second argument contains the CSV string being currently processed.

• error: Error encountered during parsing
  • message: A descriptive error message
  • code: The error code (e.g., "CSV_RECORD_INCONSISTENT_FIELDS_LENGTH")
  • record: The raw record that caused the error
• buffer: Current processing buffer encoded as an UTF-8 string

Example with inconsistent field lengths

The following example demonstrates how to handle records with inconsistent field counts:

import assert from "node:assert";
import dedent from "dedent";
import { parse } from "csv-parse";

parse(
  dedent`
    a,b,c
    invalid
    d,e,f
  `,
  {
    skip_records_with_error: true,
    on_skip: ({ message, code, record }) => {
      assert.equal(message, "Invalid Record Length: expect 3, got 1 on line 2");
      assert.equal(code, "CSV_RECORD_INCONSISTENT_FIELDS_LENGTH");
      assert.deepStrictEqual(record, ["invalid"]);
    },
  },
  function (err, records) {
    assert.deepStrictEqual(records, [
      ["a", "b", "c"],
      ["d", "e", "f"],
    ]);
  },
);

Error handling

The on_skip function is called after the parser has determined that a record should be skipped. It works in conjunction with the skip_records_with_error option:

1. When skip_records_with_error is true, invalid records are skipped and trigger the on_skip callback
2. When skip_records_with_error is false (default), parsing errors will cause the parser to emit an error and stop

Error behaviour

Errors thrown inside the on_skip function are caught by the parser and handled as if skip_records_with_error was not enabled. It's recommended to implement proper error handling within your callback function to prevent the parsing process from being interrupted.