What causes "The connection is not defined (empty)" in pentaho/pentaho-kettle?

Open the SQLFileOutput step and select a database connection

pentaho/pentaho-kettle · error · KettleStepException

The connection is not defined (empty)

Error message

The connection is not defined (empty)

What it means

Thrown by SQLFileOutput.init when the step's database connection metadata is null. Before creating the Database object, init checks meta.getDatabaseMeta(); if no connection is defined it throws KettleStepException 'The connection is not defined (empty)' and step initialization fails, preventing the transformation from running.

Solutions

Open the SQLFileOutput step and select a database connection
Add the missing connection definition to the transformation (shared/metadata connection)
When building TransMeta programmatically, set the step's databaseMeta before running
Verify the step's XML/repository entry references an existing connection name

Example fix

// before
SQLFileOutputMeta meta = new SQLFileOutputMeta();
meta.setTableName("out"); // no connection set -> init throws
// after
DatabaseMeta db = new DatabaseMeta("target", "POSTGRESQL", "Native", "user", "pass", "localhost", "db", "5432");
meta.setDatabaseMeta(db);
meta.setTableName("out");

Defensive patterns

Strategy: validation

Validate before calling

SQLFileOutputMeta meta = (SQLFileOutputMeta) stepMeta.getStepMetaInterface();
if (meta.getDatabaseMeta() == null) {
  throw new IllegalStateException("SQLFileOutput step '" + stepMeta.getName() + "' has no database connection");
}

Try / catch

try { trans.execute(null); trans.waitUntilFinished(); } catch (KettleException e) { if (e.getMessage().contains("connection is not defined")) { /* fix step config and re-run */ } }

Prevention

Always assign a database connection when configuring SQLFileOutput
When copying steps between transformations, re-link connections
Use shared/metadata connections so they persist with the environment
Programmatically validate all steps have connections before execution

When it happens

Trigger: Executing a transformation where the SQLFileOutput step has no database connection selected — connection field left empty, connection deleted from the transformation after configuring the step, or metadata loaded from XML/repository missing the connection attribute.

Common situations: Copying a step between transformations without its shared connection; connections removed during cleanup; loading transformations built in another environment where the named connection doesn't exist; programmatic TransMeta construction without setting databaseMeta.

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/5ff2382e96b68795. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/sqlfileoutput/SQLFileOutput.java:286

      retval = true;
    } catch ( Exception e ) {
      logError( "Exception trying to close file: " + e.toString() );
      setErrors( 1 );
      retval = false;
    }

    return retval;
  }

  public boolean init( StepMetaInterface smi, StepDataInterface sdi ) {
    meta = (SQLFileOutputMeta) smi;
    data = (SQLFileOutputData) sdi;

    if ( super.init( smi, sdi ) ) {
      try {
        if ( meta.getDatabaseMeta() == null ) {
          throw new KettleStepException( "The connection is not defined (empty)" );
        }
        if ( meta.getDatabaseMeta() == null ) {
          logError( BaseMessages.getString( PKG, "SQLFileOutput.Init.ConnectionMissing", getStepname() ) );
          return false;
        }
        data.db = new Database( this, meta.getDatabaseMeta() );
        data.db.shareVariablesWith( this );

        logBasic( "Connected to database [" + meta.getDatabaseMeta() + "]" );

        if ( meta.isCreateParentFolder() ) {
          // Check for parent folder
          FileObject parentfolder = null;
          try {
            // Get parent folder
            String filename = environmentSubstitute( meta.getFileName() );
            parentfolder = KettleVFS.getInstance( getTransMeta().getBowl() )
              .getFileObject( filename, getTransMeta() ).getParent();

View on GitHub (pinned to f3058517a1)