pentaho/pentaho-kettle · error · KettleException

Undefined connection

Error message

Undefined connection '%s'.

What it means

Thrown by ConnectionManager.getExistingDetails() when a connection with the requested name is not defined in the manager's registry — getDetails() returned null, violating the @NonNull contract. The connection name (possibly null/empty) is interpolated into the message via %s.

Solutions

1. Define the connection in the Pentaho connections metadata before referencing it
2. Check the connection name for typos, trailing whitespace or unresolved variables
3. Verify the connections XML/files are readable and loaded by ConnectionManager

When it happens

Trigger: Thrown at core/src/main/java/org/pentaho/di/connections/ConnectionManager.java:754 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/connections/ConnectionManager.java:754

  public <T extends ConnectionDetails> T getDetails( @Nullable String name ) {
    return (T) getConnectionDetails( name );
  }

  /**
   * Gets the details of a connection, given its name, casting it to the type parameter,
   * and throwing if it does not exist.
   *
   * @param name The connection name
   * @return The named connection details
   * @throws KettleException When a connection with the given name is not defined.
   */
  @NonNull
  public <T extends ConnectionDetails> T getExistingDetails( @Nullable String name )
    throws KettleException {

    T details = getDetails( name );
    if ( details == null ) {
      throw new KettleException( String.format( "Undefined connection '%s'.", name ) );
    }

    return details;
  }

  /**
   * Get the named connection from a specified meta store
   *
   * @param metaStore A meta store
   * @param name      The connection name
   * @return The named connection details
   */
  public ConnectionDetails getConnectionDetails( IMetaStore metaStore, String name ) {
    List<ConnectionProvider<? extends ConnectionDetails>> providers =
      Collections.list( connectionProviders.elements() );
    for ( ConnectionProvider<? extends ConnectionDetails> provider : providers ) {
      ConnectionDetails connectionDetails =
        loadElement( getMetaStoreFactory( metaStore, provider.getClassType() ), name );

View on GitHub (pinned to f3058517a1)