pentaho/pentaho-kettle · error · KettleVFSFileSystemException

ConnectionFileNameParser.ConnectionNameInvalidCharacter

ConnectionFileNameParser.ConnectionNameInvalidCharacter

Error message

ConnectionFileNameParser.ConnectionNameInvalidCharacter

What it means

validateConnectionName also enforces that each character in a connection name is a valid connection name character (isValidConnectionNameCharacter). Names containing illegal characters (e.g. '/', ':', spaces, or other reserved/unsafe characters) throw KettleVFSFileSystemException with code 'ConnectionFileNameParser.ConnectionNameInvalidCharacter', since such characters would corrupt the pvfs:// URI structure.

Solutions

1. Sanitize the connection name to allowed characters (alphanumerics, dashes, underscores — check isValidConnectionNameCharacter for the exact set).
2. Validate the name with parser.validateConnectionName(name) before registering or embedding it in a URI.
3. Move any path structure into the path portion of the URI, not the connection segment.
4. Escape or rename sources of auto-generated names (e.g. derive name from a file name but strip illegal chars).

Example fix

// before
String name = "my conn/2024";
parser.validateConnectionName( name ); // throws
// after
String name = "my-conn-2024";
parser.validateConnectionName( name ); // ok

for ( char c : connectionName.toCharArray() ) {
  if ( !Character.isLetterOrDigit( c ) && c != '-' && c != '_' ) {
    throw new IllegalArgumentException( "Illegal character in connection name: " + c );
  }
}

null

try {
  parser.validateConnectionName( connectionName );
} catch ( FileSystemException e ) {
  // sanitize the name and retry
}

When it happens

Trigger: Parsing or validating a connection name containing any character not accepted by isValidConnectionNameCharacter — e.g. 'pvfs://my conn', 'pvfs://a/b' where 'a/b' is treated as the name, or names with ':', '?', '#'.

Common situations: Users embedding slashes or spaces in connection names; file-system paths pasted wholesale as the connection name; auto-generated names from file paths or URLs.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• ConnectionFileNameParser.ConnectionNameEmpty
• vfs.provider/invalid-scheme
• vfs.provider/missing-double-slashes.error
• AbstractFileErrorHandler.Exception.CouldNotCreateFileErrorHandlerForFile
• Append file in repository is not possible

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

Appendix: source

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

      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.
   */
  public boolean isValidConnectionNameCharacter( char c ) {
    return CONNECTION_NAME_INVALID_CHARACTERS.indexOf( c ) < 0;
  }

  /**

View on GitHub (pinned to f3058517a1)