What causes "InsertUpdateMeta.Exception.ConnectionNotDefined" in pentaho/pentaho-kettle?

Open the Insert Update step and select (or create) a database connection.

pentaho/pentaho-kettle · error · KettleException

InsertUpdateMeta.Exception.ConnectionNotDefined

Error message

InsertUpdateMeta.Exception.ConnectionNotDefined

What it means

Thrown by InsertUpdateMeta.getTableFields() when the step's database connection is not defined (null), so no field lookup can be performed. Kettle requires a configured connection before it can inspect table metadata.

Solutions

Open the Insert Update step and select (or create) a database connection.
Recreate the missing shared connection in the transformation's connection tree.
Fix the .ktr XML so the step references an existing <connection> name.
If importing from another repository, ensure shared objects/connections were imported.

Example fix

// before (XML)
<connection/>
// after
<connection>CUSTOMER_DB</connection>

Defensive patterns

Strategy: validation

Validate before calling

// Guard before metadata operations
if (meta.getDatabaseMeta() == null) {
  throw new IllegalStateException("Insert Update step has no database connection configured");
}

Prevention

Assign a named shared connection to every DB step.
Never delete shared connections without re-linking steps.
When exporting/importing transformations, include shared connections.

When it happens

Trigger: getTableFields() called while getDatabaseMeta() returns null — the step has no connection assigned, typically during metadata validation or dialog field lookup on an incompletely configured step.

Common situations: A copied step lost its shared connection; the connection was deleted from the transformation; repository import skipped the shared connection; XML hand-editing removed the <connection> element.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/insertupdate/InsertUpdateMeta.java:824

        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, "InsertUpdateMeta.Exception.TableNotFound" ) );
          }
        } else {
          throw new KettleException( BaseMessages.getString( PKG, "InsertUpdateMeta.Exception.TableNotSpecified" ) );
        }
      } catch ( Exception e ) {
        throw new KettleException(
          BaseMessages.getString( PKG, "InsertUpdateMeta.Exception.ErrorGettingFields" ), e );
      } finally {
        db.close();
      }
    } else {
      throw new KettleException( BaseMessages.getString( PKG, "InsertUpdateMeta.Exception.ConnectionNotDefined" ) );
    }

  }

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

  @Override public String getMissingDatabaseConnectionInformationMessage() {
    return null;
  }

  /**
   * @param schemaName the schemaName to set
   */

View on GitHub (pinned to f3058517a1)