pentaho/pentaho-kettle · error · KettleException

SynchronizeAfterMergeMeta.Exception.ConnectionNotDefined

Error message

SynchronizeAfterMergeMeta.Exception.ConnectionNotDefined

What it means

Repository-loading guard in SynchronizeAfterMergeMeta: while getting the table fields, the flow reached a state where no database connection was defined (the connection lookup produced null), so the step cannot query the target table's schema. It is the outer catch re-raising the missing-connection condition with a localized message.

Solutions

Select a database connection in the Synchronize After Merge step dialog
Ensure the transformation contains the referenced connection and it is named correctly
Fix the XML/repository entry so the step's connection reference points to an existing DatabaseMeta
Validate the transformation with TransMeta before executing

Example fix

// before
stepMeta.setDatabaseMeta(null);
// after
stepMeta.setDatabase(transMeta.findDatabaseConnection("DB_CONN")); // must exist

Defensive patterns

Strategy: validation

Validate before calling

if (meta.getDatabaseMeta() == null) { throw new IllegalArgumentException("Synchronize After Merge: database connection not defined"); }

Try / catch

try { meta.getTableFieldsMeta(...); } catch (KettleException e) { logError("No connection defined: " + e.getMessage()); }

Prevention

Always assign a connection in the step dialog
Check transformations after copy/paste of steps for dangling connection references
Verify the connection name survives XML export/import

When it happens

Trigger: Calling getTableFieldsMeta() on a step whose database connection field was never set, or the connection was deleted from the transformation after the step referenced it.

Common situations: Copying steps between transformations where the shared connection wasn't carried over; repository connection deleted; XML import omitted <connection> element; user skipped selecting a connection in the dialog.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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

Appendix: source

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

          // 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" ) );
    }

  }

  /**
   * @return the schemaName
   */
  public String getSchemaName() {
    return schemaName;
  }

  /**
   * @param schemaName
   *          the schemaName to set
   */
  public void setSchemaName( String schemaName ) {
    this.schemaName = schemaName;

View on GitHub (pinned to f3058517a1)