{"record":{"id":"e8b526a0bdc566a6","repo":"pentaho/pentaho-kettle","slug":"sqlfileoutputmeta-exception-connectionnotdefined","errorCode":"SQLFileOutputMeta.Exception.ConnectionNotDefined","errorMessage":"SQLFileOutputMeta.Exception.ConnectionNotDefined","messagePattern":"SQLFileOutputMeta\\.Exception\\.ConnectionNotDefined","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/sqlfileoutput/SQLFileOutputMeta.java","lineNumber":817,"sourceCode":"\n        if ( !Utils.isEmpty( realTableName ) ) {\n          // Check if this table exists...\n          if ( db.checkTableExists( realSchemaName, realTableName ) ) {\n            return db.getTableFieldsMeta( realSchemaName, realTableName );\n          } else {\n            throw new KettleException( BaseMessages.getString( PKG, \"SQLFileOutputMeta.Exception.TableNotFound\" ) );\n          }\n        } else {\n          throw new KettleException( BaseMessages.getString( PKG, \"SQLFileOutputMeta.Exception.TableNotSpecified\" ) );\n        }\n      } catch ( Exception e ) {\n        throw new KettleException(\n          BaseMessages.getString( PKG, \"SQLFileOutputMeta.Exception.ErrorGettingFields\" ), e );\n      } finally {\n        db.close();\n      }\n    } else {\n      throw new KettleException( BaseMessages.getString( PKG, \"SQLFileOutputMeta.Exception.ConnectionNotDefined\" ) );\n    }\n  }\n\n  public DatabaseMeta[] getUsedDatabaseConnections() {\n    if ( databaseMeta != null ) {\n      return new DatabaseMeta[] { databaseMeta };\n    } else {\n      return super.getUsedDatabaseConnections();\n    }\n  }\n\n  /**\n   * @return the schemaName\n   */\n  public String getSchemaName() {\n    return schemaName;\n  }\n","sourceCodeStart":799,"sourceCodeEnd":835,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/sqlfileoutput/SQLFileOutputMeta.java#L799-L835","documentation":"The same table-fields method in SQLFileOutputMeta first checks whether a database connection (databaseMeta) is defined; if it is null it throws KettleException 'SQLFileOutputMeta.Exception.ConnectionNotDefined' without attempting any database work. Field metadata cannot be resolved without a connection, so this is a hard precondition failure at design time.","triggerScenarios":"Clicking 'Get Fields' (or otherwise invoking getTableFieldsMeta) in the SQL File Output dialog when no database connection has been selected in the step, or the saved connection reference was lost (connection deleted from the shared list, metadata imported without connections).","commonSituations":"Building the step before creating/selecting its DB connection; importing a transformation XML into another environment where the named connection does not exist; repository export/import losing the step-database link.","solutions":["Select an existing database connection in the step's 'Database connection' dropdown (create one via the connection dialog if needed)","Re-save/re-export the transformation making sure shared connections are included or available in the target environment","Verify after reopening the dialog that the connection selection persisted"],"exampleFix":"// before (step XML, no connection)\n<connection>null</connection>\n// after\n<connection>PROD_DB</connection> // an existing shared database connection","handlingStrategy":"validation","validationCode":"if ( meta.getDatabaseMeta() == null ) {\n  throw new IllegalStateException( \"SQL File Output: select a database connection before Get Fields\" );\n}\n// also verify it exists in the target environment's shared connections\nif ( transMeta.findDatabase( meta.getDatabaseMeta().getName() ) == null ) {\n  throw new IllegalStateException( \"Connection not present in this environment\" );\n}","typeGuard":null,"tryCatchPattern":"try {\n  RowMetaInterface fields = meta.getTableFields();\n} catch ( KettleException e ) {\n  if ( e.getMessage().contains( \"ConnectionNotDefined\" ) ) {\n    // assign a DB connection in the step dialog, then retry\n  }\n}","preventionTips":["Select the DB connection first, before configuring table/fields","Include shared connections when exporting/importing transformations","After imports, reopen steps to confirm connection references survived"],"tags":["kettle","pentaho","configuration","database","design-time"],"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"}