pentaho/pentaho-kettle · error · KettleException

No fields defined to load to database

Error message

No fields defined to load to database

What it means

GPBulkLoader.getControlFileContents throws a KettleException 'No fields defined to load to database' when building the gpload control file but the step's field stream mapping is null or empty. The generated LOAD control file must list at least one column; an empty mapping would produce invalid SQL.

Solutions

1. Open the GP Bulk Loader step dialog, go to the Fields tab and click 'Get Fields' to populate the mapping.
2. Manually add stream-field-to-table-column entries in the Fields table.
3. Verify upstream steps still emit fields, then re-run 'Get Fields'.
4. Save the transformation after mapping so the fields persist.

Example fix

// before: fields table empty in dialog
String[] streamFields = {}; // -> KettleException

// after: populate mapping (in step dialog) or programmatically
meta.setFieldStream( new String[] { "id", "name" } );
meta.setFieldTable( new String[] { "id", "name" } );

// before executing, confirm the field mapping exists
if ( meta.getFieldStream() == null || meta.getFieldStream().length == 0 ) {
  throw new KettleException( "GP Bulk Loader has no field mapping configured" );
}

When it happens

Trigger: createControlFile runs (during step initialization) with meta.getFieldStream() null or length 0 — the Fields table in the GP Bulk Loader dialog was never populated, or 'Get Fields' was never invoked after changing upstream steps.

Common situations: User filled in the target table but forgot the field mapping tab; transformation copied where the mapping failed to persist; all upstream fields removed after configuration so mapping became empty.

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

• Could not find field
• A connection of type PALO is expected
• A connection of type PALO is expected
• Caught a number format exception converting minimum length…
• ElasticSearchBulk.Error.InvalidIdField

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

Appendix: source

Thrown at plugins/gp-bulk-loader/core/src/main/java/org/pentaho/di/trans/steps/gpbulkloader/GPBulkLoader.java:165

    if ( loadAction.equalsIgnoreCase( "truncate" ) ) {
      contents.append( loadAction + " " );
      contents.append( tableName + ";" );
      contents.append( Const.CR );
    }
    contents.append( "\\COPY " );
    // Table name

    contents.append( tableName );

    // Names of columns

    contents.append( " ( " );

    String[] streamFields = meta.getFieldStream();
    String[] tableFields = meta.getFieldTable();

    if ( streamFields == null || streamFields.length == 0 ) {
      throw new KettleException( "No fields defined to load to database" );
    }

    for ( int i = 0; i < streamFields.length; i++ ) {
      if ( i != 0 ) {
        contents.append( ", " );
      }
      contents.append( dm.quoteField( tableFields[i] ) );
    }

    contents.append( " ) " );

    // The "FROM" filename
    contents.append( " FROM " );
    contents.append( inputName );

    // The "FORMAT" clause
    contents.append( " WITH CSV " );

View on GitHub (pinned to f3058517a1)