pentaho/pentaho-kettle · error · RuntimeException

The first Argument must be a Number.

Error message

The first Argument must be a Number.

What it means

The num2str() JavaScript helper function added by Pentaho Kettle's scripting step (ScriptAddedFunctions) formats a number as a string. Before formatting it explicitly checks Double.isNaN(sArg1); if the first argument is NaN it throws this RuntimeException instead of producing a useless/invalid formatted output.

Solutions

1. Check for NaN before calling num2str: if (isNaN(x)) handle/fallback instead of formatting.
2. Fix the upstream value source: ensure the input field is a valid number, not a null coerced to NaN.
3. Wrap the call in try/catch to return a default string when NaN is detected.
4. If the value came from str2num, validate the string parses before converting.

Example fix

// before
var out = num2num(value); // value may be NaN
var formatted = num2str(value);
// after
var formatted = (isNaN(value)) ? "0" : num2str(value);

function safeNum2str(x) { return (typeof x === "number" && !isNaN(x)) ? num2str(x) : "0"; }

function isFiniteNumber(v) { return typeof v === "number" && !isNaN(v) && isFinite(v); }

try { return num2str(value); } catch (e) { return "0"; }

When it happens

Trigger: Calling num2str(x) where x evaluates to Double.NaN, typically the result of a failed str2num conversion, a null mapped to NaN, or a division 0/0 inside the script.

Common situations: Chaining str2num(s) -> num2str() where the string failed to parse (str2num returns NaN); numeric fields from a previous step that are null and coerced to NaN; calculations producing NaN before formatting.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Could not apply the given format on the number : " +…
• Couldn't convert Number to String
• Function NUM2STR only works on Numbers and Integers
• The function call num2str requires 1, 2, or 3 arguments.
• The function call num2str requires at least 1 argument.

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/ce68f49f544a5648. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/script/ScriptAddedFunctions.java:1310

  }

  // Converts the given Numeric to a JScript String
  public static String num2str( ScriptEngine actualContext, Bindings actualObject, Object[] ArgList,
    Object FunctionContext ) {
    String sRC = "";
    switch ( ArgList.length ) {
      case 0:
        throw new RuntimeException( "The function call num2str requires at least 1 argument." );
      case 1:
        try {
          if ( isNull( ArgList[0] ) ) {
            return null;
          } else if ( isUndefined( ArgList[0] ) ) {
            return (String) undefinedValue;
          }
          double sArg1 = (Double) ArgList[0];
          if ( Double.isNaN( sArg1 ) ) {
            throw new RuntimeException( "The first Argument must be a Number." );
          }
          DecimalFormat formatter = new DecimalFormat();
          sRC = formatter.format( sArg1 );
        } catch ( IllegalArgumentException e ) {
          throw new RuntimeException( "Could not apply the given format on the number : " + e.getMessage() );
        }
        break;
      case 2:
        try {
          if ( isNull( ArgList, new int[] { 0, 1 } ) ) {
            return null;
          } else if ( isUndefined( ArgList, new int[] { 0, 1 } ) ) {
            return (String) undefinedValue;
          }
          double sArg1 = (Double) ArgList[0];
          if ( Double.isNaN( sArg1 ) ) {
            throw new RuntimeException( "The first Argument must be a Number." );
          }

View on GitHub (pinned to f3058517a1)