{"record":{"id":"8964b108047e9dab","repo":"pentaho/pentaho-kettle","slug":"unnamed-connection","errorCode":null,"errorMessage":"Unnamed connection","messagePattern":"Unnamed connection","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/connections/vfs/VFSConnectionManagerHelper.java","lineNumber":187,"sourceCode":"   * @return The VFS connection provider.\n   * @throws KettleException When a provider with the given key is not defined.\n   */\n  @NonNull\n  public <T extends VFSConnectionDetails> VFSConnectionProvider<T> getExistingProvider(\n    @NonNull ConnectionManager manager,\n    @NonNull T details )\n    throws KettleException {\n    return getExistingProvider( manager, details.getType() );\n  }\n  // endregion\n\n  // region Connection Root\n  @NonNull\n  public ConnectionFileName getConnectionRootFileName( @NonNull VFSConnectionDetails details ) {\n\n    String connectionName = details.getName();\n    if ( StringUtils.isEmpty( connectionName ) ) {\n      throw new IllegalArgumentException( \"Unnamed connection\" );\n    }\n\n    return new ConnectionFileName( connectionName );\n  }\n\n  @VisibleForTesting\n  @NonNull <T extends VFSConnectionDetails> FileName getConnectionRootProviderFileName(\n    @NonNull VFSConnectionFileNameTransformer<T> fileNameTransformer,\n    @NonNull T details )\n    throws KettleException {\n\n    // Example: \"pvfs://my-connection\"\n    ConnectionFileName rootPvfsFileName = getConnectionRootFileName( details );\n\n    // Example: \"s3://root-path-bucket\"\n    // Would fail if only \"s3://\"\n    return fileNameTransformer.toProviderFileName( rootPvfsFileName, details );\n  }","sourceCodeStart":169,"sourceCodeEnd":205,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/connections/vfs/VFSConnectionManagerHelper.java#L169-L205","documentation":"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.","triggerScenarios":"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.","commonSituations":"Building VFSConnectionDetails programmatically and forgetting setName; a saved connection definition missing the name attribute; copying details objects without copying the name.","solutions":["Call setName(...) with a valid non-empty connection name on the VFSConnectionDetails before use.","If details come from persisted metadata, repair the definition so the name field is populated.","Validate details.getName() is non-empty before invoking getConnectionRootFileName/rootPvfsFileName.","Reuse validateConnectionName (ConnectionFileNameParser) to check the name is legal, not just non-empty."],"exampleFix":"// before\nVFSConnectionDetails details = new VFSConnectionDetails();\nConnectionFileName root = helper.getConnectionRootFileName( details );\n// after\nVFSConnectionDetails details = new VFSConnectionDetails();\ndetails.setName( \"my-connection\" );\nConnectionFileName root = helper.getConnectionRootFileName( details );","handlingStrategy":"validation","validationCode":"if ( details == null || StringUtils.isEmpty( details.getName() ) ) {\n  throw new IllegalArgumentException( \"VFSConnectionDetails must have a non-empty name\" );\n}","typeGuard":"boolean hasName( VFSConnectionDetails d ) {\n  return d != null && !StringUtils.isEmpty( d.getName() );\n}","tryCatchPattern":"try {\n  ConnectionFileName root = helper.getConnectionRootFileName( details );\n} catch ( IllegalArgumentException e ) {\n  // prompt for / set connection name, then retry\n}","preventionTips":["Always call setName right after constructing VFSConnectionDetails","Validate connection details before persisting them","Use the parser's validateConnectionName to check both emptiness and character validity"],"tags":["vfs","connection","empty-name"],"backgroundTag":"empty-required-field","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"}