pentaho/pentaho-kettle · error · KettleDatabaseException

Unable to handle database column '" + name + "', on column…

Error message

Unable to handle database column '" + name + "', on column index " + i + " : not a handled data type

What it means

Thrown by Database.getValueFromSQLType when a result set column's java.sql.Types value maps to no Kettle ValueMetaInterface. The library supports a fixed set of SQL types; vendor-specific or exotic types fall through all handlers and reach the final throw.

Solutions

1. Cast or exclude the unhandled column in the SQL query (e.g. CAST(col AS VARCHAR))
2. Upgrade Kettle/Pentaho to a version with a broader java.sql.Types mapping
3. Check the chained cause / column name+index and adjust the table schema to a standard type
4. Extend the database dialect's type mapping via a custom DatabaseMeta plugin

Example fix

// before
SELECT id, custom_struct_col FROM mytable
// after
SELECT id, CAST(custom_struct_col AS VARCHAR(4000)) AS custom_struct_col FROM mytable

ResultSetMetaData md = rs.getMetaData();
for (int i = 1; i <= md.getColumnCount(); i++) {
  int t = md.getColumnType(i); // check for unhandled types like ARRAY, STRUCT, OTHER
}

null

try {
  meta = db.getRowInfo(rsmd, false, false);
} catch (KettleDatabaseException e) {
  if (e.getMessage().contains("not a handled data type")) {
    // re-run query with CAST for the named column
  } else { throw e; }
}

When it happens

Trigger: A table column uses an unhandled java.sql.Types constant (e.g. structured/ARRAY/REF types, or vendor extension types like Oracle's specific types) and the query metadata is converted via getRowInfo/getValueFromSQLType.

Common situations: Selecting exotic columns (BLOB variants, arrays, object/struct columns) in TableInput steps; driver reports an unusual type code after a database upgrade; custom databases whose type mapping is incomplete.

Related errors

• AccessInputMeta.Exception.ErrorSavingToRepository
• An error occurred executing SQL:
• An error occurred executing SQL:
• Cannot fetch driver metadata for
• : Comparing values can not be done with data type :

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

Appendix: source

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

    // Ask all the value meta types if they want to handle the SQL type.
    // The first to reply something gets the job...
    //
    ValueMetaInterface valueMeta = null;
    for ( ValueMetaInterface valueMetaClass : valueMetaPluginClasses ) {
      ValueMetaInterface v =
        valueMetaClass.getValueFromSQLType( databaseMeta, name, rm, i, ignoreLength, lazyConversion );
      if ( v != null ) {
        valueMeta = v;
        break;
      }
    }

    if ( valueMeta != null ) {
      return valueMeta;
    }

    throw new KettleDatabaseException( "Unable to handle database column '"
      + name + "', on column index " + i + " : not a handled data type" );
  }

  public boolean absolute( ResultSet rs, int position ) throws KettleDatabaseException {
    try {
      return rs.absolute( position );
    } catch ( SQLException e ) {
      throw new KettleDatabaseException( "Unable to move resultset to position " + position, e );
    }
  }

  public boolean relative( ResultSet rs, int rows ) throws KettleDatabaseException {
    try {
      return rs.relative( rows );
    } catch ( SQLException e ) {
      throw new KettleDatabaseException( "Unable to move the resultset forward " + rows + " rows", e );
    }
  }

View on GitHub (pinned to f3058517a1)