pentaho/pentaho-kettle · warning · KettleXMLException

Unable to read script values help file from file

Error message

Unable to read script values help file from file [<strFileName>]

What it means

ScriptValuesHelp.xparseXmlFile reads the bundled JavaScript-help XML file (strFileName) into a string and parses it with XMLHandler.loadXMLString. Any failure while reading or parsing the file (missing file, IO error, malformed XML) is wrapped in this KettleXMLException. It indicates the ScriptValues step's help documentation cannot be loaded, not a problem with the user's transformation.

Solutions

  1. Verify the script values help XML resource exists in the ui/plugin jar and is on the classpath
  2. Reinstall or repair the Pentaho Data Integration installation to restore missing resources
  3. Check file read permissions on the jar/resource location
  4. If the file is custom-edited, validate it is well-formed XML (e.g. xmllint)

Example fix

// before: loading help silently assumed resource present
KettleXMLException e = new KettleXMLException("Unable to read script values help file from file [" + strFileName + "]", e);
// after: guard caller before parsing
if ( new File( strFileName ).canRead() ) { dom = XMLHandler.loadXMLString( readFully( strFileName ) ); } else { logMissingHelp( strFileName ); }
Defensive patterns

Strategy: try-catch

Validate before calling

// Java: verify the help resource is present and readable before parsing
java.io.InputStream is = getClass().getResourceAsStream( strFileName );
if ( is == null ) throw new IllegalStateException( "Help resource missing: " + strFileName );

Type guard

boolean helpFileReadable = strFileName != null && getClass().getResourceAsStream( strFileName ) != null;

Try / catch

try { help.load(); } catch ( KettleXMLException e ) { log.warn( "Script help unavailable, continuing without it", e ); /* degrade gracefully */ }

Prevention

When it happens

Trigger: Opening the Script Values Mod step help when the help resource file is absent from the classpath/jar, unreadable, or contains invalid XML; an IOException from is.read()/close() or a parse exception from loadXMLString.

Common situations: Incomplete/partial Pentaho installation where the help XML was not shipped; corrupted jar; custom builds that excluded resource files; repackaged UI jars stripping resources.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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

Appendix: source

Thrown at ui/src/main/java/org/pentaho/di/ui/trans/steps/scriptvalues_mod/ScriptValuesHelp.java:90

          return ( elSample.getFirstChild().getNodeValue() );
        }
      }
    }
    return sRC;
  }

  private static void xparseXmlFile( String strFileName ) throws KettleXMLException {
    try {
      InputStream is = ScriptValuesHelp.class.getResourceAsStream( strFileName );
      int c;
      StringBuilder buffer = new StringBuilder();
      while ( ( c = is.read() ) != -1 ) {
        buffer.append( (char) c );
      }
      is.close();
      dom = XMLHandler.loadXMLString( buffer.toString() );
    } catch ( Exception e ) {
      throw new KettleXMLException( "Unable to read script values help file from file [" + strFileName + "]", e );
    }
  }
}

View on GitHub (pinned to f3058517a1)