pentaho/pentaho-kettle · error · KettleException

TransMeta.Exception.DatabaseErrorOccuredReadingTransformatio…

Error message

TransMeta.Exception.DatabaseErrorOccuredReadingTransformation

What it means

Wrapper thrown by loadTransformation when a KettleDatabaseException occurs while reading the transformation from the repository. The error is logged and rethrown as a KettleException with the cause attached. It indicates the repository database read failed (not that data was missing).

Solutions

Inspect the logged cause for the underlying SQL/JDBC error and fix connectivity or data issues first.
Reconnect to the repository (repository.disconnect()/connect()) and retry the load.
Check repository table integrity for the transformation's rows (R_TRANSFORMATION, R_TRANS_STEP, etc.).
Verify DB user still holds SELECT rights on repository tables.

Example fix

// before
TransMeta tm = repository.loadTransformation(name, dir, monitor, true, null); // throws KettleException
// after
try {
  TransMeta tm = repository.loadTransformation(name, dir, monitor, true, null);
} catch (KettleException e) {
  Throwable cause = e.getCause();
  if (cause instanceof KettleDatabaseException) {
    repository.disconnect();
    repository.connect(user, password); // refresh connection and retry once
  } else {
    throw e;
  }
}

Defensive patterns

Strategy: retry

Validate before calling

if (!repository.isConnected()) { repository.connect(user, password); }

Try / catch

try { return repository.loadTransformation(name, dir, monitor, true, null); } catch (KettleException e) { if (e.getCause() instanceof KettleDatabaseException && attempts < 2) { repository.disconnect(); repository.connect(user, password); continue; } throw e; }

Prevention

Keep repository connections alive/refreshed before long loads
Monitor repository DB health
Check DB user SELECT permissions on repository tables
Log and inspect the wrapped cause before assuming data corruption

When it happens

Trigger: KettleDatabaseException during any read step of loadTransformation: attribute lookups, loading steps/hops/notes/partition schemas/slaves, or repository connection failures mid-load.

Common situations: Repository database restarted or connection timed out during a long load; corrupt repository rows; prepared-statement/connection leaks; DB permissions revoked mid-session.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/repository/kdr/delegates/KettleDatabaseRepositoryTransDelegate.java:653

            + transMeta.getName() );
        }
        if ( log.isDetailed() ) {
          log.logDetailed( BaseMessages.getString( PKG, "TransMeta.Log.LoadedTransformation2", transname, String
            .valueOf( transMeta.getRepositoryDirectory() == null ) ) );
          log
            .logDetailed( BaseMessages.getString(
              PKG, "TransMeta.Log.LoadedTransformation", transname, transMeta.getRepositoryDirectory().getPath() ) );
        }

        // close prepared statements, minimize locking etc.
        //
        repository.connectionDelegate.closeAttributeLookupPreparedStatements();

        return transMeta;
      } catch ( KettleDatabaseException e ) {
        log.logError( BaseMessages.getString( PKG, "TransMeta.Log.DatabaseErrorOccuredReadingTransformation" )
          + Const.CR + e );
        throw new KettleException( BaseMessages.getString(
          PKG, "TransMeta.Exception.DatabaseErrorOccuredReadingTransformation" ), e );
      } catch ( Exception e ) {
        log.logError( BaseMessages.getString( PKG, "TransMeta.Log.DatabaseErrorOccuredReadingTransformation" )
          + Const.CR + e );
        throw new KettleException( BaseMessages.getString(
          PKG, "TransMeta.Exception.DatabaseErrorOccuredReadingTransformation2" ), e );
      } finally {
        transMeta.initializeVariablesFrom( null );
        if ( setInternalVariables ) {
          transMeta.setInternalKettleVariables();
        }
      }
    }
  }

  /**
   * Load the transformation name & other details from a repository.
   */

View on GitHub (pinned to f3058517a1)