{"record":{"id":"ce68f49f544a5648","repo":"pentaho/pentaho-kettle","slug":"the-first-argument-must-be-a-number","errorCode":null,"errorMessage":"The first Argument must be a Number.","messagePattern":"The first Argument must be a Number\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/script/ScriptAddedFunctions.java","lineNumber":1310,"sourceCode":"  }\n\n  // Converts the given Numeric to a JScript String\n  public static String num2str( ScriptEngine actualContext, Bindings actualObject, Object[] ArgList,\n    Object FunctionContext ) {\n    String sRC = \"\";\n    switch ( ArgList.length ) {\n      case 0:\n        throw new RuntimeException( \"The function call num2str requires at least 1 argument.\" );\n      case 1:\n        try {\n          if ( isNull( ArgList[0] ) ) {\n            return null;\n          } else if ( isUndefined( ArgList[0] ) ) {\n            return (String) undefinedValue;\n          }\n          double sArg1 = (Double) ArgList[0];\n          if ( Double.isNaN( sArg1 ) ) {\n            throw new RuntimeException( \"The first Argument must be a Number.\" );\n          }\n          DecimalFormat formatter = new DecimalFormat();\n          sRC = formatter.format( sArg1 );\n        } catch ( IllegalArgumentException e ) {\n          throw new RuntimeException( \"Could not apply the given format on the number : \" + e.getMessage() );\n        }\n        break;\n      case 2:\n        try {\n          if ( isNull( ArgList, new int[] { 0, 1 } ) ) {\n            return null;\n          } else if ( isUndefined( ArgList, new int[] { 0, 1 } ) ) {\n            return (String) undefinedValue;\n          }\n          double sArg1 = (Double) ArgList[0];\n          if ( Double.isNaN( sArg1 ) ) {\n            throw new RuntimeException( \"The first Argument must be a Number.\" );\n          }","sourceCodeStart":1292,"sourceCodeEnd":1328,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/script/ScriptAddedFunctions.java#L1292-L1328","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check for NaN before calling num2str: if (isNaN(x)) handle/fallback instead of formatting.","Fix the upstream value source: ensure the input field is a valid number, not a null coerced to NaN.","Wrap the call in try/catch to return a default string when NaN is detected.","If the value came from str2num, validate the string parses before converting."],"exampleFix":"// before\nvar out = num2num(value); // value may be NaN\nvar formatted = num2str(value);\n// after\nvar formatted = (isNaN(value)) ? \"0\" : num2str(value);","handlingStrategy":"validation","validationCode":"function safeNum2str(x) { return (typeof x === \"number\" && !isNaN(x)) ? num2str(x) : \"0\"; }","typeGuard":"function isFiniteNumber(v) { return typeof v === \"number\" && !isNaN(v) && isFinite(v); }","tryCatchPattern":"try { return num2str(value); } catch (e) { return \"0\"; }","preventionTips":["Always check isNaN(x) before formatting","Validate str2num results (NaN) before reformatting with num2str","Clean null/empty numeric fields upstream of the script step"],"tags":["nan","number-formatting","javascript-scripting"],"backgroundTag":"invalid-argument-value","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}