Error Handling in the JavaScript Step

If you are familiar with the error handling feature of Kettle transformation steps, you might be wondering how it can be utilized in a JavaScript step. The user interface mechanics are the same as with any other step that supports the error handling feature. It can be enabled and configured by right clicking the JavaScript step and selecting “Define error handling…”. The JavaScript code is responsible for identifying error rows and diverting them to the configured error target step. This is done using the putError() method of the _step_ object. The method requires a few arguments.

  1. a RowMetaInterface object that describes the row structure
  2. the actual error row
  3. the number of errors detected on this row
  4. an error description string for the errors
  5. a string naming the fields which caused the errors
  6. a string containing the error codes

Usually the original, unmodified input row is passed on to the error step. Therefore the first two arguments are usually specified as getInputRowMeta() and row. The rest of the arguments pretty much depend on how specific you want to be about the errors encountered.

The example transformation starts by generating random strings. For illustration purposes a subsequent JavaScript step issues errors if any of the letters ‘a’ and ‘k’ is missing from the generated string. Each missing letter constitutes an error.

The JavaScript step contains the following script:

var should_error_on_a = (value.indexOf("a") == -1)?1:0;
var should_error_on_k = (value.indexOf("k") == -1)?1:0;


	if (should_error_on_a == 1 && should_error_on_k == 1){
		throw {
			message: "Value must contain 'a' and 'k'",
			nr_errors: 2,
			field: "value",
			errcode: "ERR:003"
	else if (should_error_on_a == 1){
		throw {
			message: "Value must contain 'a'",
			nr_errors: 1,
			field: "value",
			errcode: "ERR:001"
	else if (should_error_on_k == 1){
		throw {
			message: "Value must contain 'k'",
			nr_errors: 1,
			field: "value",
			errcode: "ERR:002"
	// continue normally, passing the row on to the next step

	// divert the current row to the error step and do not pass anything to the next  step
	_step_.putError(getInputRowMeta(), row, e.nr_errors, e.message, e.field, e.errcode);

The “error handling” of the JavaScript step is configured to add all of the error fields to the stream. A preview of the “error rows” step yields the result shown in the screenshot (click to enlarge). Download the example transformation, it has no external dependencies and works in both Kettle 3.2 and 4.0.

The presented technique helps filtering errors detected by a JavaScript step in a more intuitive way. Make good use of it :-)

A practical example of this technique is given in the post about data validation and monitoring.

Related Literature

5 comments to Error Handling in the JavaScript Step

  • Ruben Silva

    Thanks very much for this! This is missing in documentation

  • Does not work in 4.4.0:

    Can’t find method org.pentaho.di.trans.step.BaseStep.putError(org.pentaho.di.core.row.RowMeta,[Ljava.lang.Object;,org.mozilla.javascript.Undefined,string,org.mozilla.javascript.Undefined,org.mozilla.javascript.Undefined).

  • tba

    Thanks man! This was really useful, a detailed error handling makes debugging so much easier.

    @Allen Jensen: Still works in PDI 5.1.0 CE

  • Nick Liu

    Hi Allen,

    I tested it on 4.4.0, if you replace these two Dummy steps with two text file output. and preview them, they are working correctly.
    But if we click “Test script” and “Get variables” in the script step, it throw out Exceptions.

    General error executing script:
    TypeError: Cannot find function putError in object org.pentaho.di.trans.steps.scriptvalues_mod.ScriptValuesModDummy@181b7493. (script#37)

  • Sameer

    Thank you very much for the explanation!

Leave a Reply




You can use these HTML tags

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>