{"record":{"id":"82496ae8c34ac078","repo":"pentaho/pentaho-kettle","slug":"database-exception-emptyconnectionerror","errorCode":null,"errorMessage":"Database.Exception.EmptyConnectionError","messagePattern":"Database\\.Exception\\.EmptyConnectionError","errorType":"exception","errorClass":"KettleDatabaseException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/core/database/Database.java","lineNumber":3397,"sourceCode":"          throw new KettleDatabaseException(\n            \"Only 1 row was expected as a result of a lookup, and at least 2 were found!\" );\n        }\n      }\n      return ret;\n    } catch ( SQLException ex ) {\n      throw new KettleDatabaseException( \"Error looking up row in database\", ex );\n    } finally {\n      log.snap( Metrics.METRIC_DATABASE_GET_LOOKUP_STOP, databaseMeta.getName() );\n    }\n  }\n\n  public DatabaseMetaData getDatabaseMetaData() throws KettleDatabaseException {\n    if ( dbmd == null ) {\n      try {\n        log.snap( Metrics.METRIC_DATABASE_GET_DBMETA_START, databaseMeta.getName() );\n\n        if ( connection == null ) {\n          throw new KettleDatabaseException( BaseMessages.getString( PKG,\n            \"Database.Exception.EmptyConnectionError\", databaseMeta.getDatabaseName() ) );\n        }\n\n        dbmd = connection.getMetaData(); // Only get the metadata once!\n      } catch ( Exception e ) {\n        throw new KettleDatabaseException( BaseMessages.getString( PKG,\n          \"Database.Exception.UnableToGetMetadata\" ), e );\n      } finally {\n        log.snap( Metrics.METRIC_DATABASE_GET_DBMETA_STOP, databaseMeta.getName() );\n      }\n    }\n    return dbmd;\n  }\n\n  public String getDDL( String tablename, RowMetaInterface fields ) throws KettleDatabaseException {\n    return getDDL( tablename, fields, null, false, null, true );\n  }\n","sourceCodeStart":3379,"sourceCodeEnd":3415,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/core/database/Database.java#L3379-L3415","documentation":"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.","triggerScenarios":"Calling getDatabaseMetaData() before connect(), or after disconnect() / a closed connection set connection to null, when dbmd has not been cached yet.","commonSituations":"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.","solutions":["Call database.connect() before requesting metadata","Check that the earlier connect() succeeded (it throws or logs on failure)","Do not reuse a Database instance after disconnect(); create a new one","Verify the DatabaseMeta is properly initialized with connection details"],"exampleFix":"// before\nDatabase db = new Database(parent, databaseMeta);\nDatabaseMetaData md = db.getDatabaseMetaData(); // connection is null\n// after\nDatabase db = new Database(parent, databaseMeta);\ndb.connect();\nDatabaseMetaData md = db.getDatabaseMetaData();","handlingStrategy":"validation","validationCode":"// guard before requesting metadata\nif ( !database.checkConnection() ) {\n  database.connect(); // establishes connection, throws if credentials/network are wrong\n}\nDatabaseMetaData md = database.getDatabaseMetaData();","typeGuard":null,"tryCatchPattern":"try {\n  md = database.getDatabaseMetaData();\n} catch ( KettleDatabaseException e ) {\n  logError(\"No active connection for metadata retrieval: \" + e.getMessage());\n  throw e;\n}","preventionTips":["Always call connect() before any metadata operation","Never reuse a Database object after disconnect()","Check connect() return/exceptions before proceeding","Encapsulate connect+use+disconnect in one helper method"],"tags":["jdbc","database","connection","metadata"],"backgroundTag":"connection-refused","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"}