pentaho/pentaho-kettle · error · KettleException

AbstractFileErrorHandler.Exception.CouldNotCreateFileErrorHandlerForFile

AbstractFileErrorHandler.Exception.CouldNotCreateFileErrorHandlerForFile

Error message

AbstractFileErrorHandler.Exception.CouldNotCreateFileErrorHandlerForFile

What it means

KettleException thrown by AbstractFileErrorHandler.getWriter() when creating the OutputStreamWriter for an error-handling file fails for a given file part. It wraps the underlying KettleFileException or IOException with a message identifying the error-lineage file URI.

Solutions

Create the configured error-handling directory and grant the process write permission
Verify the charset/encoding string is a valid supported encoding (e.g. 'UTF-8')
Check the target file URI in the message for typos or invalid characters
Run the transformation/Kettle process under a user with access to the error directory

Example fix

// before: encoding typo
handler = new FileErrorHandlerContentLineNumber(..., "utf_8", ...)
// after
handler = new FileErrorHandlerContentLineNumber(..., "UTF-8", ...)

Defensive patterns

Strategy: validation

Validate before calling

import org.apache.commons.vfs2.FileObject;
// Before enabling file error handling:
FileObject errFile = fsManager.resolveFile(errorDirUri + "/error.txt");
FileObject parent = errFile.getParent();
if (parent == null || !parent.exists() || !parent.isWriteable()) {
  throw new IllegalStateException("Error dir missing/unwritable: " + errorDirUri);
}
if (encoding != null && !java.nio.charset.Charset.isSupported(encoding)) {
  throw new IllegalStateException("Unsupported encoding: " + encoding);
}

Try / catch

try {
  errorHandler.handleLineError(lineNr, part);
} catch (KettleException e) {
  log.error("Error-lineage file unusable: " + e.getMessage(), e);
  // fail the transformation or route bad rows to a fallback table
  throw e;
}

Prevention

Create and chmod the error-handling directory before running the transformation
Use exact supported charset names ('UTF-8', not typos)
Test error handling with a deliberately bad row before production runs
Monitor disk space on the error directory volume

When it happens

Trigger: getWriter(source) called on first write for a part; KettleVFS.getOutputStream(file, false) or new OutputStreamWriter(...) throws — target directory doesn't exist, no write permission, invalid filename/URI, or (when encoding != null) unsupported charset name.

Common situations: Text file input error handling configured with an error directory that doesn't exist or isn't writable; bad 'encoding' value typed in the step dialog (e.g. 'utf-8 ' typo); read-only mounted error directory.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/step/errorhandling/AbstractFileErrorHandler.java:125

      if ( outputStreamWriter != null ) {
        return outputStreamWriter;
      }
      FileObject file =
        getReplayFilename( destinationDirectory, processingFilename, dateString, fileExtension, source );
      ResultFile resultFile =
        new ResultFile( ResultFile.FILE_TYPE_GENERAL, file, baseStep.getTransMeta().getName(), baseStep
          .getStepname() );
      baseStep.addResultFile( resultFile );
      try {
        if ( isBlank( encoding ) ) {
          outputStreamWriter = new OutputStreamWriter( KettleVFS.getInstance( DefaultBowl.getInstance() )
                                                       .getOutputStream( file, false ) );
        } else {
          outputStreamWriter = new OutputStreamWriter( KettleVFS.getInstance( DefaultBowl.getInstance() )
                                                       .getOutputStream( file, false ), encoding );
        }
      } catch ( Exception e ) {
        throw new KettleException( BaseMessages.getString(
          PKG, "AbstractFileErrorHandler.Exception.CouldNotCreateFileErrorHandlerForFile" )
          + file.getName().getURI(), e );
      }
      writers.put( source, outputStreamWriter );
      return outputStreamWriter;
    } catch ( KettleFileException e ) {
      throw new KettleException( BaseMessages.getString(
        PKG, "AbstractFileErrorHandler.Exception.CouldNotCreateFileErrorHandlerForFile" ), e );
    }
  }

  public void close() throws KettleException {
    for ( Iterator<Writer> iter = writers.values().iterator(); iter.hasNext(); ) {
      close( iter.next() );
    }
    writers = new HashMap<Object, Writer>();

  }

View on GitHub (pinned to f3058517a1)