{"record":{"id":"7a3539215db95cc2","repo":"pentaho/pentaho-kettle","slug":"error-looking-up-row-in-database","errorCode":null,"errorMessage":"Error looking up row in database","messagePattern":"Error looking up row in database","errorType":"exception","errorClass":"KettleDatabaseException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/core/database/Database.java","lineNumber":3385,"sourceCode":"  public Object[] getLookup( PreparedStatement ps, boolean failOnMultipleResults, boolean lazyConversion )\n    throws KettleDatabaseException {\n    log.snap( Metrics.METRIC_DATABASE_GET_LOOKUP_START, databaseMeta.getName() );\n    try ( ResultSet res = ps.executeQuery() ) {\n      Object[] ret = getRow( res, lazyConversion );\n\n      if ( failOnMultipleResults ) {\n        if ( ret != null && res.next() ) {\n          // if the previous row was null, there's no reason to try res.next()\n          // again.\n          // on DB2 this will even cause an exception (because of the buggy DB2\n          // JDBC driver).\n          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,","sourceCodeStart":3367,"sourceCodeEnd":3403,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/core/database/Database.java#L3367-L3403","documentation":"Generic wrapper thrown by Database's lookup method when the JDBC query used for a row lookup throws a SQLException. The meaningful cause (syntax error, closed connection, timeout, permission) is attached as the chained exception.","triggerScenarios":"Any SQLException during execution of the prepared lookup SELECT - e.g. connection already closed/timed out, invalid column or table name in the lookup definition, wrong parameter types, or driver-level errors.","commonSituations":"Stale connections after DB failover or network drops; renamed/dropped tables or columns after schema changes; mismatched key field types between stream and table; insufficient SELECT grants.","solutions":["Inspect the chained SQLException cause for the driver's actual message","Verify the connection is alive (call database.connect() or check network/DB availability)","Confirm the lookup table and field names match the current schema","Check the user has SELECT permission on the lookup table"],"exampleFix":"// before\ndatabase.getLookup(tablename, keys, values); // connection long idle, dropped by firewall\n// after\nif ( !database.checkConnection() ) { database.disconnect(); database.connect(); }\ndatabase.getLookup(tablename, keys, values);","handlingStrategy":"try-catch","validationCode":"// ensure connection is alive before the lookup\nif ( !database.checkConnection() ) { database.disconnect(); database.connect(); }","typeGuard":null,"tryCatchPattern":"try {\n  return database.getLookup(tablename, keys, values);\n} catch ( KettleDatabaseException e ) {\n  Throwable cause = e.getCause();\n  if ( cause instanceof SQLException && isConnectionError((SQLException) cause) ) {\n    database.disconnect(); database.connect();\n    return database.getLookup(tablename, keys, values); // one retry on connection loss\n  }\n  throw e;\n}","preventionTips":["Enable connection keep-alive/validation queries on the pool","Re-check schema names after database migrations","Verify SELECT grants for the integration user","Match key field types between stream and table definitions"],"tags":["jdbc","database","sql","lookup"],"backgroundTag":"database-query-failed","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"}