pentaho/pentaho-kettle · error · KettleVFSFileSystemException

ConnectionFileNameParser.ConnectionNameEmpty

ConnectionFileNameParser.ConnectionNameEmpty

Error message

ConnectionFileNameParser.ConnectionNameEmpty

What it means

ConnectionFileNameParser.validateConnectionName rejects connection names that are null or empty, throwing a KettleVFSFileSystemException with code 'ConnectionFileNameParser.ConnectionNameEmpty'. Every pvfs:// URI requires a connection name as its authority segment; without one the URI cannot identify a connection.

Solutions

1. Include the connection name in the URI: 'pvfs://my-connection/path'.
2. Validate the connection name is non-empty before building the URI.
3. Check that the variable/parameter holding the connection name is populated at runtime.
4. Call parser.validateConnectionName(name) up front to fail early with a precise message.

Example fix

// before
String uri = "pvfs://" + connectionName + "/data"; // connectionName is ""
// after
if ( StringUtils.isEmpty( connectionName ) ) {
  throw new IllegalArgumentException( "connectionName is required" );
}
String uri = "pvfs://" + connectionName + "/data";

if ( connectionName == null || connectionName.isEmpty() ) {
  throw new IllegalArgumentException( "Connection name is required in pvfs URIs" );
}

boolean hasConnectionName( String uri ) {
  int i = uri.indexOf( "://" );
  return i >= 0 && uri.length() > i + 3 && uri.charAt( i + 3 ) != '/';
}

try {
  parser.parseUri( uri );
} catch ( FileSystemException e ) {
  if ( String.valueOf( e.getMessage() ).contains( "ConnectionNameEmpty" ) ) {
    // rebuild uri with an explicit connection name
  }
}

When it happens

Trigger: Parsing a URI like 'pvfs://' (no '//name') or 'pvfs:///' where the connection segment is absent; calling validateConnectionName("") or validateConnectionName(null) directly.

Common situations: Users entering a VFS URL without the connection name; string concatenation producing 'pvfs://' when a variable holding the connection name is empty; template variables not substituted in connection paths.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• ConnectionFileNameParser.ConnectionNameInvalidCharacter
• Unnamed connection
• vfs.provider/invalid-scheme
• vfs.provider/missing-double-slashes.error
• AbstractFileErrorHandler.Exception.CouldNotCreateFileErrorHandlerForFile

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/connections/vfs/provider/ConnectionFileNameParser.java:159

  }

  @NonNull
  public static ConnectionFileNameParser getInstance() {
    if ( instance == null ) {
      instance = new ConnectionFileNameParser();
    }

    return instance;
  }

  @NonNull
  protected ConnectionFileNameUtils getConnectionFileNameUtils() {
    return connectionFileNameUtils;
  }

  public void validateConnectionName( @Nullable String connectionName ) throws FileSystemException {
    if ( StringUtils.isEmpty( connectionName ) ) {
      throw new KettleVFSFileSystemException( "ConnectionFileNameParser.ConnectionNameEmpty" );
    }

    for ( char c : connectionName.toCharArray() ) {
      if ( !isValidConnectionNameCharacter( c ) ) {
        throw new KettleVFSFileSystemException(
          "ConnectionFileNameParser.ConnectionNameInvalidCharacter",
          connectionName,
          c );
      }
    }
  }

  /**
   * Determines if a given character is a valid in a connection name.
   *
   * @param c The character to test.
   * @return {@code true} if the character is valid; {@code false}, otherwise.
   */

View on GitHub (pinned to f3058517a1)