pentaho/pentaho-kettle · error · IllegalArgumentException

Unnamed connection

Error message

Unnamed connection

What it means

VFSConnectionManagerHelper.getConnectionRootFileName derives the connection's PVFS root FileName from details.getName(). Every VFS connection must have a non-empty name, because the name becomes the root segment of the pvfs:// URI. An unnamed connection has no valid root, so an IllegalArgumentException with message 'Unnamed connection' is thrown.

Solutions

  1. Call setName(...) with a valid non-empty connection name on the VFSConnectionDetails before use.
  2. If details come from persisted metadata, repair the definition so the name field is populated.
  3. Validate details.getName() is non-empty before invoking getConnectionRootFileName/rootPvfsFileName.
  4. Reuse validateConnectionName (ConnectionFileNameParser) to check the name is legal, not just non-empty.

Example fix

// before
VFSConnectionDetails details = new VFSConnectionDetails();
ConnectionFileName root = helper.getConnectionRootFileName( details );
// after
VFSConnectionDetails details = new VFSConnectionDetails();
details.setName( "my-connection" );
ConnectionFileName root = helper.getConnectionRootFileName( details );
Defensive patterns

Strategy: validation

Validate before calling

if ( details == null || StringUtils.isEmpty( details.getName() ) ) {
  throw new IllegalArgumentException( "VFSConnectionDetails must have a non-empty name" );
}

Type guard

boolean hasName( VFSConnectionDetails d ) {
  return d != null && !StringUtils.isEmpty( d.getName() );
}

Try / catch

try {
  ConnectionFileName root = helper.getConnectionRootFileName( details );
} catch ( IllegalArgumentException e ) {
  // prompt for / set connection name, then retry
}

Prevention

When it happens

Trigger: Calling getConnectionRootFileName (directly or via rootPvfsFileName) with VFSConnectionDetails whose getName() returns null or the empty string — e.g. freshly constructed details never given a name, or a connection deserialized without its name field.

Common situations: Building VFSConnectionDetails programmatically and forgetting setName; a saved connection definition missing the name attribute; copying details objects without copying the name.

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

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

Appendix: source

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

   * @return The VFS connection provider.
   * @throws KettleException When a provider with the given key is not defined.
   */
  @NonNull
  public <T extends VFSConnectionDetails> VFSConnectionProvider<T> getExistingProvider(
    @NonNull ConnectionManager manager,
    @NonNull T details )
    throws KettleException {
    return getExistingProvider( manager, details.getType() );
  }
  // endregion

  // region Connection Root
  @NonNull
  public ConnectionFileName getConnectionRootFileName( @NonNull VFSConnectionDetails details ) {

    String connectionName = details.getName();
    if ( StringUtils.isEmpty( connectionName ) ) {
      throw new IllegalArgumentException( "Unnamed connection" );
    }

    return new ConnectionFileName( connectionName );
  }

  @VisibleForTesting
  @NonNull <T extends VFSConnectionDetails> FileName getConnectionRootProviderFileName(
    @NonNull VFSConnectionFileNameTransformer<T> fileNameTransformer,
    @NonNull T details )
    throws KettleException {

    // Example: "pvfs://my-connection"
    ConnectionFileName rootPvfsFileName = getConnectionRootFileName( details );

    // Example: "s3://root-path-bucket"
    // Would fail if only "s3://"
    return fileNameTransformer.toProviderFileName( rootPvfsFileName, details );
  }

View on GitHub (pinned to f3058517a1)