pentaho/pentaho-kettle · error · KettleDatabaseException

Database.Exception.EmptyConnectionError

Error message

Database.Exception.EmptyConnectionError

What it means

Thrown by Database.getDatabaseMetaData() when the JDBC Connection is null, meaning no connection has been established (or it was disconnected) before requesting metadata. The message is localized from the message bundle and includes the configured database name.

Solutions

  1. Call database.connect() before requesting metadata
  2. Check that the earlier connect() succeeded (it throws or logs on failure)
  3. Do not reuse a Database instance after disconnect(); create a new one
  4. Verify the DatabaseMeta is properly initialized with connection details

Example fix

// before
Database db = new Database(parent, databaseMeta);
DatabaseMetaData md = db.getDatabaseMetaData(); // connection is null
// after
Database db = new Database(parent, databaseMeta);
db.connect();
DatabaseMetaData md = db.getDatabaseMetaData();
Defensive patterns

Strategy: validation

Validate before calling

// guard before requesting metadata
if ( !database.checkConnection() ) {
  database.connect(); // establishes connection, throws if credentials/network are wrong
}
DatabaseMetaData md = database.getDatabaseMetaData();

Try / catch

try {
  md = database.getDatabaseMetaData();
} catch ( KettleDatabaseException e ) {
  logError("No active connection for metadata retrieval: " + e.getMessage());
  throw e;
}

Prevention

When it happens

Trigger: Calling getDatabaseMetaData() before connect(), or after disconnect() / a closed connection set connection to null, when dbmd has not been cached yet.

Common situations: Forgetting to call connect() in custom steps/plugins; using a Database object after its connection was closed in another step; failed connect silently leaving connection null.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/database/Database.java:3397

          throw new KettleDatabaseException(
            "Only 1 row was expected as a result of a lookup, and at least 2 were found!" );
        }
      }
      return ret;
    } catch ( SQLException ex ) {
      throw new KettleDatabaseException( "Error looking up row in database", ex );
    } finally {
      log.snap( Metrics.METRIC_DATABASE_GET_LOOKUP_STOP, databaseMeta.getName() );
    }
  }

  public DatabaseMetaData getDatabaseMetaData() throws KettleDatabaseException {
    if ( dbmd == null ) {
      try {
        log.snap( Metrics.METRIC_DATABASE_GET_DBMETA_START, databaseMeta.getName() );

        if ( connection == null ) {
          throw new KettleDatabaseException( BaseMessages.getString( PKG,
            "Database.Exception.EmptyConnectionError", databaseMeta.getDatabaseName() ) );
        }

        dbmd = connection.getMetaData(); // Only get the metadata once!
      } catch ( Exception e ) {
        throw new KettleDatabaseException( BaseMessages.getString( PKG,
          "Database.Exception.UnableToGetMetadata" ), e );
      } finally {
        log.snap( Metrics.METRIC_DATABASE_GET_DBMETA_STOP, databaseMeta.getName() );
      }
    }
    return dbmd;
  }

  public String getDDL( String tablename, RowMetaInterface fields ) throws KettleDatabaseException {
    return getDDL( tablename, fields, null, false, null, true );
  }

View on GitHub (pinned to f3058517a1)