pentaho/pentaho-kettle · error · KettleException

Root path contains invalid relative segments

Error message

Root path contains invalid relative segments: '%s'

What it means

normalizeRootPath cleans a configured connection root path: it fixes separators and normalises the path via Apache Commons VFS UriParser.normalisePath. If normalisation fails (the path contains invalid relative segments such as malformed '..' usage), a KettleException wrapping the FileSystemException is thrown, since the root path cannot be safely resolved.

Solutions

1. Fix the configured root path so relative segments resolve within the root (remove or reduce '..').
2. Validate the path yourself (e.g. count '..' vs path depth) before calling getResolvedRootPath.
3. Prefer absolute, fully-normalised root paths in connection configuration.
4. Catch KettleException around getResolvedRootPath and surface the offending rootPath to the user for correction.

Example fix

// before
String root = helper.getResolvedRootPath( details ); // rootPath = "a/../../.."
// after
String rootPath = details.getRootPath();
if ( rootPath == null || rootPath.split( "/" ).length < countUpSegments( rootPath ) ) {
  rootPath = "/"; // or reject the config early
}
String root = helper.getResolvedRootPath( details );

long ups = Arrays.stream( rootPath.split( "/" ) ).filter( ".."::equals ).count();
if ( rootPath != null && ups >= rootPath.split( "/" ).length ) {
  throw new IllegalArgumentException( "Root path climbs above root: " + rootPath );
}

null

try {
  String root = helper.getResolvedRootPath( details );
} catch ( KettleException e ) {
  // surface details.getRootPath() to the user for correction
}

When it happens

Trigger: Calling getResolvedRootPath with a root path containing invalid relative segments — e.g. '..' that climbs above the root, a path like '../../..', or sequences that Commons VFS normalisation rejects.

Common situations: Hand-typed root paths in connection settings with excessive '../' segments; template-substituted paths that expand to too many parent steps; paths copied between Windows/Unix with mixed separators plus '..'.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• ConnectionFileSystem.ExpectedConnectionNotFound
• CustomVfsSettingsParser.Log.FailedToLoad
• FileSystemConfigBuilder could not parse parameter:
• Invalid repository type
• Only local files are supported at this time, file [

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/connections/vfs/VFSConnectionManagerHelper.java:280

    return null;
  }

  @Nullable
  protected String normalizeRootPath( @NonNull String rootPath ) throws KettleException {
    rootPath = rootPath.trim();
    if ( rootPath.isEmpty() ) {
      return null;
    }

    StringBuilder rootPathBuilder = new StringBuilder( rootPath );

    UriParser.fixSeparators( rootPathBuilder );

    try {
      UriParser.normalisePath( rootPathBuilder );
    } catch ( FileSystemException e ) {
      throw new KettleException( String.format( "Root path contains invalid relative segments: '%s'", rootPath ), e );
    }

    // Remove leading separator.
    vfsConnectionFileNameUtils.trimLeadingSeparator( rootPathBuilder );

    // Example: "" | "root/path"

    return rootPathBuilder.length() > 0
      ? rootPathBuilder.toString()
      : null;
  }
  // endregion

  // region test

  /**
   * Tests if a VFS connection is valid, given its details, optionally, with certain testing options.
   * <p>

View on GitHub (pinned to f3058517a1)