{"record":{"id":"5ff2382e96b68795","repo":"pentaho/pentaho-kettle","slug":"the-connection-is-not-defined-empty","errorCode":null,"errorMessage":"The connection is not defined (empty)","messagePattern":"The connection is not defined \\(empty\\)","errorType":"exception","errorClass":"KettleStepException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/sqlfileoutput/SQLFileOutput.java","lineNumber":286,"sourceCode":"\n      retval = true;\n    } catch ( Exception e ) {\n      logError( \"Exception trying to close file: \" + e.toString() );\n      setErrors( 1 );\n      retval = false;\n    }\n\n    return retval;\n  }\n\n  public boolean init( StepMetaInterface smi, StepDataInterface sdi ) {\n    meta = (SQLFileOutputMeta) smi;\n    data = (SQLFileOutputData) sdi;\n\n    if ( super.init( smi, sdi ) ) {\n      try {\n        if ( meta.getDatabaseMeta() == null ) {\n          throw new KettleStepException( \"The connection is not defined (empty)\" );\n        }\n        if ( meta.getDatabaseMeta() == null ) {\n          logError( BaseMessages.getString( PKG, \"SQLFileOutput.Init.ConnectionMissing\", getStepname() ) );\n          return false;\n        }\n        data.db = new Database( this, meta.getDatabaseMeta() );\n        data.db.shareVariablesWith( this );\n\n        logBasic( \"Connected to database [\" + meta.getDatabaseMeta() + \"]\" );\n\n        if ( meta.isCreateParentFolder() ) {\n          // Check for parent folder\n          FileObject parentfolder = null;\n          try {\n            // Get parent folder\n            String filename = environmentSubstitute( meta.getFileName() );\n            parentfolder = KettleVFS.getInstance( getTransMeta().getBowl() )\n              .getFileObject( filename, getTransMeta() ).getParent();","sourceCodeStart":268,"sourceCodeEnd":304,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/sqlfileoutput/SQLFileOutput.java#L268-L304","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nSQLFileOutputMeta meta = new SQLFileOutputMeta();\nmeta.setTableName(\"out\"); // no connection set -> init throws\n// after\nDatabaseMeta db = new DatabaseMeta(\"target\", \"POSTGRESQL\", \"Native\", \"user\", \"pass\", \"localhost\", \"db\", \"5432\");\nmeta.setDatabaseMeta(db);\nmeta.setTableName(\"out\");","handlingStrategy":"validation","validationCode":"SQLFileOutputMeta meta = (SQLFileOutputMeta) stepMeta.getStepMetaInterface();\nif (meta.getDatabaseMeta() == null) {\n  throw new IllegalStateException(\"SQLFileOutput step '\" + stepMeta.getName() + \"' has no database connection\");\n}","typeGuard":null,"tryCatchPattern":"try { trans.execute(null); trans.waitUntilFinished(); } catch (KettleException e) { if (e.getMessage().contains(\"connection is not defined\")) { /* fix step config and re-run */ } }","preventionTips":["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"],"tags":["configuration","database-connection","step-init"],"backgroundTag":"missing-required-config-field","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}