What causes "Filename is missing!" in pentaho/pentaho-kettle?

Pass a non-empty filename resolved via the environment/variable space (variableSpace.environmentSubstitute(path))

pentaho/pentaho-kettle · error · KettleException

Filename is missing!

Error message

Filename is missing!

What it means

Thrown by the SQL-script execution helper (Database.java:5290, executesStatementsFromFile path) as a plain KettleException when the filename parameter is null or empty. The method runs SQL statements from a file and refuses to proceed without a path. Note it is a KettleException, not KettleDatabaseException.

Solutions

Pass a non-empty filename resolved via the environment/variable space (variableSpace.environmentSubstitute(path))
Check Utils.isEmpty(filename) before calling and fail early with a clear message
Verify the job/transform parameter that supplies the SQL script path is defined and populated
If the file is optional, skip the call when the path is blank instead of invoking it
Use KettleVFS to confirm the resolved path exists before execution

Example fix

// before
database.executesStatementsFromFile( sqlFilename, true );
// after
if ( !Utils.isEmpty( sqlFilename ) ) {
  String resolved = variableSpace.environmentSubstitute( sqlFilename );
  database.executesStatementsFromFile( resolved, true );
}

Defensive patterns

Strategy: validation

Validate before calling

String resolved = variableSpace.environmentSubstitute( sqlFilename );
if ( Utils.isEmpty( resolved ) ) {
  throw new IllegalArgumentException( "SQL script filename must be provided" );
}
if ( !KettleVFS.getInstance( bowl ).getFileObject( resolved ).exists() ) {
  throw new IllegalArgumentException( "SQL script not found: " + resolved );
}

Try / catch

try {
  database.executesStatementsFromFile( filename, true );
} catch ( KettleException e ) {
  if ( e.getMessage().contains( "Filename is missing" ) ) {
    // resolve and repopulate the path variable, then retry
  } else {
    throw e;
  }
}

Prevention

Resolve all file paths through environmentSubstitute before use
Validate required path parameters at job/transform init
Skip the call gracefully when the script path is intentionally blank
Check file existence with KettleVFS before execution

When it happens

Trigger: Calling Database.executesStatementsFromFile(filename, ...) (or the wrapped script-execution method) with filename == null or "".

Common situations: A transformation/job variable holding the SQL file path was never set (missing parameter); environment variable or internal variable not resolved; hard-coded path removed during refactor; GUI field left blank when building metadata programmatically.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/database/Database.java:5290

    this.nrExecutedCommits = nrExecutedCommits;
  }

  /**
   * Execute an SQL statement inside a file on the database connection (has to be open)
   *
   * @param filename The file that contains SQL to execute
   * @return a Result object indicating the number of lines read, deleted, inserted, updated, ...
   * @throws KettleDatabaseException in case anything goes wrong.
   * @sendSinglestatement send one statement
   */
  public Result execStatementsFromFile( Bowl bowl, String filename, boolean sendSinglestatement )
    throws KettleException {
    FileObject sqlFile = null;
    InputStream is = null;
    InputStreamReader bis = null;
    try {
      if ( Utils.isEmpty( filename ) ) {
        throw new KettleException( "Filename is missing!" );
      }
      sqlFile = KettleVFS.getInstance( bowl ).getFileObject( filename );
      if ( !sqlFile.exists() ) {
        throw new KettleException( "We can not find file [" + filename + "]!" );
      }

      is = KettleVFS.getInputStream( sqlFile );
      bis = new InputStreamReader( new BufferedInputStream( is, 500 ) );

      BufferedReader buff = new BufferedReader( bis );
      String sLine;
      StringBuilder sql = new StringBuilder( Const.CR );

      while ( ( sLine = buff.readLine() ) != null ) {
        if ( Utils.isEmpty( sLine ) ) {
          sql.append( Const.CR );
        } else {
          sql.append( Const.CR ).append( sLine );

View on GitHub (pinned to f3058517a1)