{"record":{"id":"5c672754da5a9e17","repo":"pentaho/pentaho-kettle","slug":"connectionfileobject-undefinedconnection","errorCode":"ConnectionFileObject.UndefinedConnection","errorMessage":"ConnectionFileObject.UndefinedConnection","messagePattern":"ConnectionFileObject\\.UndefinedConnection","errorType":"exception","errorClass":"KettleVFSFileSystemException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/connections/vfs/provider/UndefinedConnectionFileObject.java","lineNumber":42,"sourceCode":"\n/**\n * This class represents a connection file object whose connection does not exist.\n */\nclass UndefinedConnectionFileObject extends ConnectionFileObject {\n  public UndefinedConnectionFileObject( @NonNull ConnectionFileName name, @NonNull ConnectionFileSystem fs ) {\n    super( name, fs );\n  }\n\n  @Override\n  @Nullable\n  public FileObject getResolvedFileObject() {\n    return null;\n  }\n\n  @Override\n  @NonNull\n  protected AbstractFileObject<?> requireResolvedFileObject() throws FileSystemException {\n    throw new KettleVFSFileSystemException( \"ConnectionFileObject.UndefinedConnection\", getName().toString() );\n  }\n\n  @Override\n  public FileType getType() throws FileSystemException {\n    return FileType.IMAGINARY;\n  }\n\n  @Override\n  public boolean isAttached() {\n    return true;\n  }\n\n  @Override\n  public boolean isWriteable() throws FileSystemException {\n    return false;\n  }\n\n  @Override","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/connections/vfs/provider/UndefinedConnectionFileObject.java#L24-L60","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Define the missing named connection in the Kettle metadata/environment before running","Fix the connection name in the URI or transformation/job configuration (check spelling)","Export/import the connection metadata so the target environment has the same connections as dev"],"exampleFix":"// before\nFileObject f = KettleVFS.getFileObject(\"pvfs://myCon/file.csv\"); // 'myCon' undefined\n// after\nDatabaseMeta/NamedConnection must exist:\nFileObject f = KettleVFS.getFileObject(\"pvfs://myConnection/file.csv\"); // matches defined connection","handlingStrategy":"validation","validationCode":"Connection connection = metadataProvider.getConnection(name); if (connection == null) throw new IllegalArgumentException(\"Connection not defined: \" + name);","typeGuard":"boolean isUndefinedConnection(FileObject fo) { return fo instanceof UndefinedConnectionFileObject; }","tryCatchPattern":"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; } }","preventionTips":["Keep connection metadata synchronized across dev/test/prod environments","Validate all pvfs:// URIs reference defined connections before running transformations","Watch for typos in connection names in configuration files"],"tags":["vfs","undefined-connection","pentaho-kettle"],"backgroundTag":"resource-not-found","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}