pentaho/pentaho-kettle · error · KettleException

Undefined connection provider for key

Error message

Undefined connection provider for key '%s'.

What it means

VFSConnectionManagerHelper.getExistingProvider looks up a VFSConnectionProvider in the ConnectionManager by key. If no provider is registered under that key, it throws a KettleException stating the provider is undefined. The key identifies a named VFS connection registration; without a provider, no file operations can be performed.

Solutions

1. Register the VFS connection under this key before use (add the connection to the ConnectionManager / repository).
2. Print available connection keys and verify exact spelling/case of the key.
3. Guard with getProvider(...) first and handle the null case instead of using getExistingProvider.
4. Ensure the connection definition file/metadata was actually loaded in this environment.

Example fix

// before
VFSConnectionProvider<Details> p = helper.getExistingProvider( manager, "myConn" );
// after
VFSConnectionProvider<Details> p = helper.getProvider( manager, "myConn" );
if ( p == null ) {
  manager.addConnection( "myConn", details ); // or fail fast with a clear message
  p = helper.getExistingProvider( manager, "myConn" );
}

if ( helper.getProvider( manager, key ) == null ) {
  throw new IllegalStateException( "Connection '" + key + "' is not registered; register it first" );
}

null

try {
  VFSConnectionProvider<Details> p = helper.getExistingProvider( manager, key );
} catch ( KettleException e ) {
  // log key, list registered connections, rethrow with actionable message
}

When it happens

Trigger: Calling getExistingProvider (or provider(...)) with a key for which no VFS connection was ever registered, a misspelled connection name, or a key whose connection was removed from the ConnectionManager before the lookup.

Common situations: Typo in connection name passed to the helper; environment migration where connection definitions were not imported; a connection deleted by another part of the pipeline; case-sensitivity differences in the key.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• Connection not found: " + name
• ConnectionFileProvider.FailedLoadConnectionManager
• ConnectionFileSystem.ConnectionManagerGone
• 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/00e460f661208702. Report an issue: GitHub.

Appendix: source

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

   * A provider key is either its own {@link ConnectionProvider#getKey()} or a registered alias, via
   * {@link ConnectionManager#addLookupFilter(LookupFilter)}.
   * <p>
   * This method will throw a {@link ClassCastException} exception if a provider with the given key is defined which is
   * not of the expected type, {@link VFSConnectionProvider<T>}.
   *
   * @param key The provider key.
   * @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,
    @Nullable String key )
    throws KettleException {

    VFSConnectionProvider<T> provider = getProvider( manager, key );
    if ( provider == null ) {
      throw new KettleException( String.format( "Undefined connection provider for key '%s'.", key ) );
    }

    return provider;
  }

  /**
   * Gets a VFS provider, given the details of the VFS connection.
   * <p>
   * This method will throw a {@link ClassCastException} exception if a provider with the given key is defined which is
   * not of the expected type, {@link VFSConnectionProvider<T>}.
   *
   * @param details The details of the VFS connection.
   * @return The VFS connection provider, if one exists; {@code null}, otherwise.
   */
  @Nullable
  public <T extends VFSConnectionDetails> VFSConnectionProvider<T> getProvider(
    @NonNull ConnectionManager manager,
    @Nullable T details ) {

View on GitHub (pinned to f3058517a1)