pentaho/pentaho-kettle · error · KettlePluginException

Unable to find standard kettle variables definition file…

Error message

Unable to find standard kettle variables definition file: kettleVariables.xml

What it means

KettleVariablesList.init() loads kettleVariables.xml from the classpath to register all standard Kettle variables. If the resource cannot be found on the classpath (in the package or at the classpath root), it throws KettlePluginException. This means the Kettle installation is incomplete or the classpath is broken.

Solutions

1. Ensure kettle-variables.xml / kettleVariables.xml is present in the kettle-engine jar on the classpath.
2. Add the engine resources directory to the classpath if running a custom/embedded setup.
3. Rebuild with resource filtering included or re-download the full Kettle distribution.
4. Check for a custom ClassLoader that filters resources; load via the correct parent classloader.

Example fix

// before
KettleVariablesList.init(); // fails if engine resources missing
// after
URL check = KettleVariablesList.class.getResource(Const.KETTLE_VARIABLES_FILE);
if (check == null) {
  check = KettleVariablesList.class.getResource("/" + Const.KETTLE_VARIABLES_FILE);
}
if (check == null) throw new IllegalStateException("kettleVariables.xml missing from classpath");
KettleVariablesList.init();

InputStream in = KettleVariablesList.class.getResourceAsStream("/" + Const.KETTLE_VARIABLES_FILE);
if (in == null) throw new IllegalStateException("kettleVariables.xml missing from classpath");

try { KettleVariablesList.init(); } catch (KettlePluginException e) { throw new RuntimeException("Kettle resources missing on classpath", e); }

When it happens

Trigger: Calling KettleVariablesList.init() (directly or indirectly during Kettle environment init) when getResourceAsStream(Const.KETTLE_VARIABLES_FILE) returns null for both 'kettleVariables.xml' and '/kettleVariables.xml'.

Common situations: A stripped-down/shaded jar excludes the resource file; a custom classloader doesn't see engine resources; an incomplete build or wrong artifact version on the classpath; packaging resource filters dropped the XML.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Failed to initialize default DocumentBuilder for XML parsing
• Unable to find native plugins definition file
• AvroInput.Error.UnsupportedTopLevelStructure
• Cannot find WSDL file: + _wsdlName
• Central Log Store is not initialized!!!

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/core/KettleVariablesList.java:64

    return KettleVariablesListHelper.INSTANCE;
  }

  private Map<String, String> descriptionMap;
  private Map<String, String> defaultValueMap;

  public static void init() throws KettleException {

    InputStream inputStream = null;
    try {
      KettleVariablesList variablesList = getInstance();

      inputStream = variablesList.getClass().getResourceAsStream( Const.KETTLE_VARIABLES_FILE );

      if ( inputStream == null ) {
        inputStream = variablesList.getClass().getResourceAsStream( "/" + Const.KETTLE_VARIABLES_FILE );
      }
      if ( inputStream == null ) {
        throw new KettlePluginException( "Unable to find standard kettle variables definition file: " + Const.KETTLE_VARIABLES_FILE );
      }
      Document doc = XMLHandler.loadXMLFile( inputStream, null, false, false );
      Node varsNode = XMLHandler.getSubNode( doc, "kettle-variables" );
      int nrVars = XMLHandler.countNodes( varsNode, "kettle-variable" );
      for ( int i = 0; i < nrVars; i++ ) {
        Node varNode = XMLHandler.getSubNodeByNr( varsNode, "kettle-variable", i );
        String description = XMLHandler.getTagValue( varNode, "description" );
        String variable = XMLHandler.getTagValue( varNode, "variable" );
        String defaultValue = XMLHandler.getTagValue( varNode, "default-value" );

        variablesList.getDescriptionMap().put( variable, description );
        variablesList.getDefaultValueMap().put( variable, defaultValue );
      }
    } catch ( Exception e ) {
      throw new KettleException( "Unable to read file '" + Const.KETTLE_VARIABLES_FILE + "'", e );
    } finally {
      if ( inputStream != null ) {
        try {

View on GitHub (pinned to f3058517a1)