pentaho/pentaho-kettle · error · KettleException

CsvInput.Log.OnlyLocalFilesAreSupported

Error message

CsvInput.Log.OnlyLocalFilesAreSupported

What it means

The CSV input step uses Java NIO (FileChannel/ByteBuffer) for fast binary reading, which only works on local filesystem files. After resolving the file via KettleVFS it checks the FileObject type; if it is not a LocalFile instance, this KettleException is thrown because NIO cannot be applied to remote/protocol-based filesystems.

Solutions

  1. Move/copy the file to a local filesystem path and configure that path in the step.
  2. Add a preceding step (e.g. a shell/script step or Get File) that downloads the remote file locally, then feed the local path to CsvInput.
  3. Use the Text File Input step instead of Csv Input if remote VFS support is required, as it goes through the VFS stream API rather than NIO.

Example fix

// before
filename = "sftp://server/data/input.csv"
// after (downloaded first, then read locally)
filename = "/tmp/input.csv"
Defensive patterns

Strategy: validation

Validate before calling

// ensure the path is a local file before the transformation reads it
java.io.File f = new java.io.File(localPath);
if (!f.isFile() || !f.canRead()) throw new IllegalStateException("Not a readable local file: " + localPath);

Try / catch

try { ... } catch (KettleException e) {
  logError("CSV Input requires local files; check VFS scheme of: " + filename, e);
  setErrors(1);
}

Prevention

When it happens

Trigger: data.filenames[filenr] resolves through VFS to a non-local file: e.g. an sftp://, http://, smb://, hdfs:// or webdav:// URL is configured (directly or passed via the filename field from a previous step) and openNextFile is called from processRow.

Common situations: Pointing CsvInput at an SFTP or HDFS file expecting transparent remote access; a previous step passing remote file names into the filename field; cluster environments where files exist only on a shared network mount accessed via a non-local VFS scheme.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/csvinput/CsvInput.java:334

    try {

      // Close the previous file...
      //
      data.closeFile();

      if ( data.filenr >= data.filenames.length ) {
        return false;
      }

      // Open the next one...
      //
      data.fieldsMapping = createFieldMapping( data.filenames[data.filenr], meta );
      FileObject fileObject = KettleVFS.getInstance( getTransMeta().getBowl() )
        .getFileObject( data.filenames[ data.filenr ], getTransMeta() );
      if ( !( fileObject instanceof LocalFile ) ) {
        // We can only use NIO on local files at the moment, so that's what we limit ourselves to.
        //
        throw new KettleException( BaseMessages.getString( PKG, "CsvInput.Log.OnlyLocalFilesAreSupported" ) );
      }

      if ( meta.isLazyConversionActive() ) {
        data.binaryFilename = data.filenames[ data.filenr ].getBytes();
      }

      String vfsFilename = KettleVFS.getFilename( fileObject );

      int bomSize = getBOMSize( vfsFilename );

      data.fis = new FileInputStream( vfsFilename );
      if ( 0 != bomSize ) {
        data.fis.skip( bomSize );
      }

      data.fc = data.fis.getChannel();
      data.bb = ByteBuffer.allocateDirect( data.preferredBufferSize );

View on GitHub (pinned to f3058517a1)