pentaho/pentaho-kettle · error · KettleVFSFileSystemException

ConnectionFileObject.UndefinedConnection

ConnectionFileObject.UndefinedConnection

Error message

ConnectionFileObject.UndefinedConnection

What it means

UndefinedConnectionFileObject represents a placeholder file object for a connection name that has not been defined in the Kettle environment/metadata. Because there is no real connection to resolve, requireResolvedFileObject() throws KettleVFSFileSystemException with code ConnectionFileObject.UndefinedConnection, carrying the undefined connection name. It indicates the referenced connection does not exist.

Solutions

1. Define the missing named connection in the Kettle metadata/environment before running
2. Fix the connection name in the URI or transformation/job configuration (check spelling)
3. Export/import the connection metadata so the target environment has the same connections as dev

Example fix

// before
FileObject f = KettleVFS.getFileObject("pvfs://myCon/file.csv"); // 'myCon' undefined
// after
DatabaseMeta/NamedConnection must exist:
FileObject f = KettleVFS.getFileObject("pvfs://myConnection/file.csv"); // matches defined connection

Connection connection = metadataProvider.getConnection(name); if (connection == null) throw new IllegalArgumentException("Connection not defined: " + name);

boolean isUndefinedConnection(FileObject fo) { return fo instanceof UndefinedConnectionFileObject; }

try { resolved = fileObject.requireResolvedFileObject(); } catch (KettleVFSFileSystemException e) { if ("ConnectionFileObject.UndefinedConnection".equals(e.getCode())) { /* connection missing: define it or fail fast with clear message */ } else { throw e; } }

When it happens

Trigger: Resolving a pvfs:// URI whose connection name has no matching defined connection (e.g. 'pvfs://myConn/file.txt' when 'myConn' is missing from the metadata), then invoking an operation that needs the resolved backing file object.

Common situations: Typos in connection names in transformation/job configs; connections deleted or not migrated to the target environment; running transformations on a server without the required named connections defined; environment-specific metadata not imported.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• ConnectionFileObject.PVFSRoot.UnsupportedOperation
• Error opening file [" + data.filename + "]!
• ExcelInputLog.ImageFileNotExists
• KettleException( e )
• KettleException( e )

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/connections/vfs/provider/UndefinedConnectionFileObject.java:42

/**
 * This class represents a connection file object whose connection does not exist.
 */
class UndefinedConnectionFileObject extends ConnectionFileObject {
  public UndefinedConnectionFileObject( @NonNull ConnectionFileName name, @NonNull ConnectionFileSystem fs ) {
    super( name, fs );
  }

  @Override
  @Nullable
  public FileObject getResolvedFileObject() {
    return null;
  }

  @Override
  @NonNull
  protected AbstractFileObject<?> requireResolvedFileObject() throws FileSystemException {
    throw new KettleVFSFileSystemException( "ConnectionFileObject.UndefinedConnection", getName().toString() );
  }

  @Override
  public FileType getType() throws FileSystemException {
    return FileType.IMAGINARY;
  }

  @Override
  public boolean isAttached() {
    return true;
  }

  @Override
  public boolean isWriteable() throws FileSystemException {
    return false;
  }

  @Override

View on GitHub (pinned to f3058517a1)