What causes "Error retrieving controlfile string" in pentaho/pentaho-kettle?

Correct the control file path in the step dialog; ensure the directory exists and is writable.

pentaho/pentaho-kettle · error · KettleException

Error retrieving controlfile string

Error message

Error retrieving controlfile string

What it means

After appending the executable, createCommandLine resolves the control file path via VFS and appends control='<path>' to the sqlldr command. A KettleFileException while resolving or getting the filename of the configured control file is wrapped in this KettleException.

Solutions

Correct the control file path in the step dialog; ensure the directory exists and is writable.
Resolve/define any environment variables used in the path.
Verify no concurrent execution deletes or moves the generated control file before sqlldr is invoked.
Use a simple absolute path or a valid VFS URL (e.g. file:///tmp/load.ctl).

Example fix

// before (unresolved variable)
control file = ${TMPDIR}/load.ctl
// after
control file = /tmp/load.ctl

Defensive patterns

Strategy: validation

Validate before calling

// Java: pre-check the configured control file path
String ctl = transMeta.environmentSubstitute(meta.getControlFile());
if (ctl != null) {
  File dir = new File(ctl).getAbsoluteFile().getParentFile();
  if (dir == null || !dir.isDirectory() || !dir.canWrite()) {
    throw new IllegalStateException("Control file directory missing/unwritable: " + dir);
  }
}

Try / catch

try {
  trans.execute(null);
} catch (KettleException e) {
  if (String.valueOf(e.getMessage()).contains("Error retrieving controlfile")) {
    // check cause for path/variable resolution failure
  }
}

Prevention

Use absolute, variable-free paths or ensure variables are defined at runtime.
Avoid concurrent executions sharing the same control file path.
Create target directories during deployment, not at first run.

When it happens

Trigger: meta.getControlFile() is non-null but getFileObject(meta.getControlFile(), transMeta) or getFilename throws KettleFileException during createCommandLine (execute).

Common situations: Control file path contains an unresolvable variable; the path points to a directory or unwritable location; VFS scheme typo; file deleted between generation and command build in concurrent executions.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: source

Thrown at plugins/oracle-bulk-loader/impl/src/main/java/org/pentaho/di/trans/steps/orabulkloader/OraBulkLoader.java:370

        String sqlldr = getFilename( fileObject );
        sb.append( sqlldr );
      } catch ( KettleFileException ex ) {
        throw new KettleException( "Error retrieving sqlldr string", ex );
      }
    } else {
      throw new KettleException( "No sqlldr application specified" );
    }

    if ( meta.getControlFile() != null ) {
      try {
        FileObject fileObject =
          getFileObject( meta.getControlFile(), getTransMeta() );

        sb.append( " control=\'" );
        sb.append( getFilename( fileObject ) );
        sb.append( "\'" );
      } catch ( KettleFileException ex ) {
        throw new KettleException( "Error retrieving controlfile string", ex );
      }
    } else {
      throw new KettleException( "No control file specified" );
    }

    if ( OraBulkLoaderMeta.METHOD_AUTO_CONCURRENT.equals( meta.getLoadMethod() ) ) {
      sb.append( " data=\'-\'" );
    }

    if ( meta.getLogFile() != null ) {
      try {
        FileObject fileObject =
          getFileObject( meta.getLogFile(), getTransMeta() );

        sb.append( " log=\'" );
        sb.append( getFilename( fileObject ) );
        sb.append( "\'" );
      } catch ( KettleFileException ex ) {

View on GitHub (pinned to f3058517a1)