{"record":{"id":"364e81a218435d6c","repo":"pentaho/pentaho-kettle","slug":"error0002","errorCode":"ERROR0002","errorMessage":"DatabaseLookup.ERROR0002.UnableToDetermineFieldsOfTable + schemaTable + \"]\"","messagePattern":"DatabaseLookup\\.ERROR0002\\.UnableToDetermineFieldsOfTable \\+ schemaTable \\+ \"\\]\"","errorType":"exception","errorClass":"KettleStepException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/databaselookup/DatabaseLookup.java","lineNumber":253,"sourceCode":"      // Fill in the types...\n      for ( int i = 0; i < keyFields.length; i++ ) {\n        ValueMetaInterface key = fields.searchValueMeta( keyFields[ i ] );\n        if ( key != null ) {\n          data.keytypes[ i ] = key.getType();\n        } else {\n          throw new KettleStepException( BaseMessages.getString(\n            PKG, \"DatabaseLookup.ERROR0001.FieldRequired5.Exception\" )\n            + keyFields[ i ]\n            + BaseMessages.getString( PKG, \"DatabaseLookup.ERROR0001.FieldRequired6.Exception\" ) );\n        }\n      }\n\n      if ( shouldDatabaseReturnValueTypeBeUsed() ) {\n        useReturnValueTypeFromDatabase( fields );\n      }\n\n    } else {\n      throw new KettleStepException( BaseMessages.getString(\n        PKG, \"DatabaseLookup.ERROR0002.UnableToDetermineFieldsOfTable\" )\n        + schemaTable + \"]\" );\n    }\n  }\n\n  /*\n   * Checks whether the return value type of fields should use the ones configured in the database instead\n   * of the ones chosen in the step UI\n   * If KETTLE_COMPATIBILITY_DB_LOOKUP_USE_FIELDS_RETURN_TYPE_CHOSEN_IN_UI kettle property is set to \"Y\"\n   * the return type of the fields is the one chosen in the step UI.\n   * If the kettle property is not set or set to \"N\" then the return type of the fields is the one configured in the database\n   */\n  private boolean shouldDatabaseReturnValueTypeBeUsed() {\n    String skipLookupReturnFields = getVariable( Const.KETTLE_COMPATIBILITY_DB_LOOKUP_USE_FIELDS_RETURN_TYPE_CHOSEN_IN_UI, \"N\" );\n    return !ValueMetaBase.convertStringToBoolean( Const.NVL( skipLookupReturnFields, \"N\" ) );\n  }\n\n  /*","sourceCodeStart":235,"sourceCodeEnd":271,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/databaselookup/DatabaseLookup.java#L235-L271","documentation":"DatabaseLookup.determineFieldsTypesQueryingDb() calls db.getTableFields(schemaTable) to read the lookup table's row metadata. If the database returns null metadata (table or schema.table not found), it throws KettleStepException 'Unable to determine the fields of table' + schemaTable + ']'.","triggerScenarios":"processRow() runs a lookup whose key/value types must be determined from the DB and Database.getTableFields() returns null because schemaTable does not exist, is inaccessible to the user, or the schema name is wrong/missing.","commonSituations":"Lookup table dropped or renamed in the target database; wrong schema prefix after migrating environments (dev vs prod); insufficient grants to read metadata for the table; case-sensitivity issues on uppercase/lowercase table names.","solutions":["Verify schema.table exists and is spelled correctly (including case) in the step's database connection","Check the DB user has SELECT/metadata privileges on that table","Add the correct schema name if the table lives in a non-default schema","Preview the Database Lookup step to refresh and validate table metadata before running"],"exampleFix":"// before (step config)\nschemaTable = \"employees\";        // not in default schema\n// after\nschemaTable = \"hr.employees\";     // schema-qualified table","handlingStrategy":"validation","validationCode":"// confirm the lookup table exists and is readable before executing\nRowMetaInterface fields = db.getTableFields( schemaTable );\nif ( fields == null ) {\n  throw new KettleException( \"Lookup table not found or not readable: \" + schemaTable );\n}","typeGuard":null,"tryCatchPattern":"try {\n  rows = db.getLookupRows( ... );\n} catch ( KettleStepException e ) {\n  if ( e.getMessage() != null && e.getMessage().contains( \"Unable to determine the fields of table\" ) ) {\n    // check schema.table spelling, grants, then retry\n  } else { throw e; }\n}","preventionTips":["Qualify lookup tables with schema names to avoid default-schema surprises","Grant the connection user SELECT (and metadata) access to the lookup table","Run table existence checks in an init/pre-flight step","Watch for case-sensitive identifier differences across environments"],"tags":["kettle","database","table-not-found","lookup"],"backgroundTag":"resource-not-found","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"}