What causes "SynchronizeAfterMergeMeta.Exception.TableNotFound" in pentaho/pentaho-kettle?

Create the target table in the database (or run the migration) before executing/validating the transformation

pentaho/pentaho-kettle · error · KettleException

SynchronizeAfterMergeMeta.Exception.TableNotFound

Error message

SynchronizeAfterMergeMeta.Exception.TableNotFound

What it means

During validation the step connects to the target database and, when the real (schema-qualified) table name is non-empty, calls db.checkTableExists(). If the table does not exist it throws KettleException 'TableNotFound' instead of proceeding to read its field metadata via getTableFieldsMeta.

Solutions

Create the target table in the database (or run the migration) before executing/validating the transformation
Verify the step's database connection points at the intended environment and schema
Fix the table name (and schema name) in the step dialog; check any variable used for the table name resolves correctly
If the table name comes from a field/variable, ensure the value is correct at validation time and the connection user can see the table (grants/synonyms)

Example fix

// before: table ORDERS missing in schema SALES
SQL> CREATE TABLE SALES.ORDERS (ORDER_ID NUMBER, AMOUNT NUMBER(10,2), ...);
// or fix step config: target schema.table = SALES.ORDERS (was PUBLIC.ORDRS)

Defensive patterns

Strategy: validation

Validate before calling

// Before running/validating, confirm the table exists
DatabaseMeta dbMeta = transMeta.findDatabaseConnection("MY_CONN");
Database db = new Database(loggingObject, dbMeta);
db.connect();
if (!db.checkTableExists(schema, tableName)) {
  throw new IllegalStateException("Target table missing: " + schema + "." + tableName);
}
db.disconnect();

Try / catch

try { trans.execute(...); }
catch (KettleException e) { if (e.getMessage().contains("TableNotFound")) { log.error("Create/locate table before running: " + schema + "." + table); } else throw e; }

Prevention

Run schema migrations before deploying transformations
Verify the database connection points at the right environment
Qualify tables with explicit schema names
Check variables used for table names resolve correctly in each environment

When it happens

Trigger: The configured target table (and schema) does not exist in the connected database at validation time — wrong connection selected, wrong schema name, table dropped, or table name resolved from a table-name-in-field variable that evaluates incorrectly.

Common situations: Pointing the transformation at a dev/test database missing the table; schema not set so lookup goes to the wrong default schema; typo in table name; migration not yet run in the target environment.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/synchronizeaftermerge/SynchronizeAfterMergeMeta.java:1047

      return super.getUsedDatabaseConnections();
    }
  }

  public RowMetaInterface getRequiredFields( VariableSpace space ) throws KettleException {
    String realTableName = space.environmentSubstitute( tableName );
    String realSchemaName = space.environmentSubstitute( schemaName );

    if ( databaseMeta != null ) {
      Database db = new Database( loggingObject, databaseMeta );
      try {
        db.connect();

        if ( !Utils.isEmpty( realTableName ) ) {
          // Check if this table exists...
          if ( db.checkTableExists( realSchemaName, realTableName ) ) {
            return db.getTableFieldsMeta( realSchemaName, realTableName );
          } else {
            throw new KettleException( BaseMessages.getString(
              PKG, "SynchronizeAfterMergeMeta.Exception.TableNotFound" ) );
          }
        } else {
          throw new KettleException( BaseMessages.getString(
            PKG, "SynchronizeAfterMergeMeta.Exception.TableNotSpecified" ) );
        }
      } catch ( Exception e ) {
        throw new KettleException( BaseMessages.getString(
          PKG, "SynchronizeAfterMergeMeta.Exception.ErrorGettingFields" ), e );
      } finally {
        db.close();
      }
    } else {
      throw new KettleException( BaseMessages.getString(
        PKG, "SynchronizeAfterMergeMeta.Exception.ConnectionNotDefined" ) );
    }

  }

View on GitHub (pinned to f3058517a1)