pentaho/pentaho-kettle · error · FileAlreadyExistsException

FileAlreadyExistsException(file)

Error message

FileAlreadyExistsException(file)

What it means

PentahoAvroOutputFormat.setOutputFile throws FileAlreadyExistsException when the requested output file already exists in the Kettle VFS and the caller did not pass override=true. This is a safety guard so Avro output runs do not silently overwrite existing data files.

Solutions

  1. Delete or archive the existing file at the target path before running
  2. Enable the override/overwrite option so setOutputFile is called with override=true
  3. Use a dynamic filename (timestamps/variables) so each run gets a unique path
  4. Catch FileAlreadyExistsException and prompt the user or route to a new file

Example fix

// before
format.setOutputFile( "file:///data/out.avro", false );
// after
if ( KettleVFS.getInstance( bowl ).fileExists( "file:///data/out.avro", variableSpace ) ) {
  // delete or pick a new name, or explicitly allow overwrite
}
format.setOutputFile( "file:///data/out.avro", true );
Defensive patterns

Strategy: validation

Validate before calling

KettleVFS vfs = KettleVFS.getInstance( bowl );
if ( !override && vfs.fileExists( outputPath, variableSpace ) ) {
  outputPath = generateUniqueName( outputPath ); // or delete / prompt
}
format.setOutputFile( outputPath, override );

Try / catch

try {
  format.setOutputFile( file, override );
} catch ( FileAlreadyExistsException e ) {
  // choose a new filename or delete the existing file, then retry
}

Prevention

When it happens

Trigger: Calling setOutputFile(file, false) (or an equivalent step configuration with 'override existing file' unchecked) when KettleVFS.fileExists(file) returns true for the target path.

Common situations: Re-running a transformation that writes to a fixed filename without deleting the previous output; forgetting to enable the overwrite option in the Avro output step dialog; output path pointing at a file left over from a failed previous run.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

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

Appendix: source

Thrown at plugins/avro-format/core/src/main/java/org/pentaho/di/trans/steps/avro/output/PentahoAvroOutputFormat.java:116

      errors.append( "\n" );
      errors.append( date + " - Please set the Avro Schema Record name." );
    }
    if ( !StringUtils.isEmpty( errors.toString() ) ) {
      throw new Exception( errors.toString() );
    }
  }

  @Override
  public void setFields( List<? extends IAvroOutputField> fields ) throws Exception {
    this.fields = fields;
    schema = null;
    schemaObjectNode = null;
  }


  @Override public void setOutputFile( String file, boolean override ) throws Exception {
    if ( !override && KettleVFS.getInstance( bowl ).fileExists( file, variableSpace ) ) {
      throw new FileAlreadyExistsException( file );
    }

    this.outputFilename = file;
  }

  @Override
  public void setCompression( CodecFactory compression ) {
    this.codecFactory = compression;
  }

  @Override
  public void setNameSpace( String namespace ) {
    this.nameSpace = namespace;
    schema = null;
    schemaObjectNode = null;
  }

  @Override

View on GitHub (pinned to f3058517a1)