pentaho/pentaho-kettle · error · KettleFileException

PurRepository.ERROR_0008_TRANSFORMATION_PATH_INVALID

PurRepository.ERROR_0008_TRANSFORMATION_PATH_INVALID

Error message

PurRepository.ERROR_0008_TRANSFORMATION_PATH_INVALID (localized, takes transName)

What it means

Thrown by PurRepository.loadTransformation when the path computed from the name cannot be resolved — typically because the name contained a variable that is not defined at runtime, leaving absPath blank. ERROR_0008_TRANSFORMATION_PATH_INVALID includes the original name for diagnostics.

Solutions

Define the referenced variables (kettle.properties, job parameters) before loading
Replace variable-based names with absolute repository paths when loading outside the variable's scope
Check that the transformation name/path resolves correctly and log it before calling loadTransformation

Example fix

// before
String name = "${Internal.Job.Filename.Directory}/mytrans"; // variable unset at runtime
TransMeta tm = repository.loadTransformation(name, null, monitor, null, false);
// after
String name = "/home/admin/mytrans"; // or ensure variable defined in kettle.properties
TransMeta tm = repository.loadTransformation(name, null, monitor, null, false);

Defensive patterns

Strategy: validation

Validate before calling

String resolved = resolveVariables(transName); // e.g. environment.getVariable(...)
if (resolved == null || resolved.trim().isEmpty() || resolved.contains("${")) {
  throw new IllegalArgumentException("Transformation path unresolved: " + transName);
}

Try / catch

try {
  return repository.loadTransformation(transName, dir, monitor, revision, readOnly);
} catch (KettleFileException e) {
  if (String.valueOf(e.getMessage()).contains("TRANSFORMATION_PATH_INVALID")) {
    log.error("Could not resolve path for " + transName + "; check variable definitions", e);
  }
  throw e;
}

Prevention

Define all referenced variables in kettle.properties or job parameters
Prefer absolute repository paths over variable-based paths when loading outside job scope
Log the resolved path before loading to catch blank substitutions

When it happens

Trigger: loadTransformation called with a name containing ${INTERNAL_...} or user variables that the repository cannot resolve; getPath() returns null/empty because the variable substitution yields a blank path.

Common situations: Using ${Internal.Job.Filename.Directory} outside a job context; exporting jobs that reference variables not set on the target machine; runtime environments missing variable definitions from kettle.properties.

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

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

Appendix: source

Thrown at plugins/pur/core/src/main/java/org/pentaho/di/repository/pur/PurRepository.java:2452

  throws KettleException {
    String absPath = null;
    try {
      // if transName is empty, we cannot load the transformation - the transformation path was likely not provided
      // by the user
      if ( StringUtils.isBlank( transName ) ) {
        throw new KettleFileException( BaseMessages.getString( PKG,
          "PurRepository.ERROR_0007_TRANSFORMATION_NAME_MISSING" ) );
      }
      try {
        absPath = getPath( transName, parentDir, RepositoryObjectType.TRANSFORMATION );
      } catch ( Exception e ) {
        // ignore and handle null value below
      }
      // if absPath is empty, we cannot load the transformation - the path provided by the user was likely defined as a
      // variable that is not available at runtime
      if ( StringUtils.isBlank( absPath )  ) {
        // Couldn't resolve path, throw an exception
        throw new KettleFileException( BaseMessages.getString( PKG,
          "PurRepository.ERROR_0008_TRANSFORMATION_PATH_INVALID", transName ) );
      }

      RepositoryFile file;
      NodeRepositoryFileData data = null;
      ObjectRevision revision = null;

      readWriteLock.readLock().lock();
      try {
        file = pur.getFile( absPath );
        if ( versionId != null ) {
          // need to go back to server to get versioned info
          file = pur.getFileAtVersion( file.getId(), versionId );
        }

        // if file is null, we cannot load the transformation - the provided path provided by the user is likely not a
        // valid file
        if ( file == null ) {

View on GitHub (pinned to f3058517a1)