What causes "throw new KettleException( e );" in pentaho/pentaho-kettle?

Fix the fileName entry at index i so it resolves to a valid path after variable substitution.

pentaho/pentaho-kettle · error · KettleException

throw new KettleException( e );

Error message

throw new KettleException( e );

What it means

GetFileNamesMeta.exportResources() wraps any exception that occurs while converting the step's hard-coded file names into repository-relative references (via NameResourceInterface.nameResource) into a bare KettleException. It means resource exporting for this step failed, typically because a file object could not be resolved against the variable space.

Solutions

Fix the fileName entry at index i so it resolves to a valid path after variable substitution.
Verify the VFS scheme prefix (file:, sftp:, etc.) is correct and the provider is available.
Set required Kettle environment variables before exporting.
Inspect the wrapped cause for the precise VFS failure.

Example fix

// before
String file = "${MY_DIR}/data.csv"; // MY_DIR unset -> invalid substitution
// after
String file = space.environmentSubstitute("${MY_DIR}/data.csv");
if (Utils.isEmpty(file) || !file.contains(":") && !new File(file).exists()) { logError("Unresolved: " + file); }

Defensive patterns

Strategy: validation

Validate before calling

for (String f : meta.getFileName()) { String r = space.environmentSubstitute(f); if (Utils.isEmpty(r) || r.contains("${")) throw new IllegalArgumentException("Unresolved variable in file name: " + f); }

Try / catch

try { transMeta.exportResources(...); } catch (KettleException e) { log.error("Resource export failed: " + e.getMessage(), e); }

Prevention

Define all used variables before export
Test file paths with KettleVFS.fileExists() first
Use valid VFS scheme prefixes
Export from an environment where referenced shares are reachable

When it happens

Trigger: Exporting a transformation's resources when space.environmentSubstitute(fileName[i]) points to a non-resolvable/invalid path, or KettleVFS.getFileObject / nameResource throws (VFS error, bad URI, missing file system plugin).

Common situations: Exporting with environment variables unset so substituted paths are malformed; filenames containing illegal VFS scheme characters; referencing network shares unavailable during export.

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

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/getfilenames/GetFileNamesMeta.java:827

      Repository repository, IMetaStore metaStore ) throws KettleException {
    try {
      // The object that we're modifying here is a copy of the original!
      // So let's change the filename from relative to absolute by grabbing the file object...
      // In case the name of the file comes from previous steps, forget about this!
      //
      if ( !filefield ) {

        // Replace the filename ONLY (folder or filename)
        //
        for ( int i = 0; i < fileName.length; i++ ) {
          FileObject fileObject = KettleVFS.getInstance( executionBowl )
            .getFileObject( space.environmentSubstitute( fileName[i] ), space );
          fileName[i] = namingInterface.nameResource( fileObject, space, Utils.isEmpty( fileMask[i] ) );
        }
      }
      return null;
    } catch ( Exception e ) {
      throw new KettleException( e );
    }
  }

  @Override
  public StepHelperInterface getStepHelperInterface() {
    return new GetFileNamesHelper( this );
  }
}

View on GitHub (pinned to f3058517a1)