pentaho/pentaho-kettle · error · KettleException

TextFileInputDialog.Exception.ErrorGettingFirstLines

Error message

TextFileInputDialog.Exception.ErrorGettingFirstLines

What it means

getFirst() reads the first N lines of a text file (for sampling/preview) and wraps any underlying I/O, decoding, or parsing failure in a KettleException with the message 'ErrorGettingFirstLines', including the requested line count and the file URI. The library throws it because the caller (dialog preview, content guessing) cannot proceed without sample lines. The original exception is chained as the cause.

Solutions

  1. Verify the file exists and the URI is reachable (open it manually or with a file browser before previewing).
  2. Check VFS credentials/scheme configuration for remote files (SFTP, S3, HTTP).
  3. Try re-reading with the correct character encoding in the Content tab.
  4. Open the chained cause (e.getCause()) to identify the root IO/decode failure and fix that.
  5. Increase logging to TRACE on org.pentaho.di.trans.steps.fileinput to see which line/read failed.

Example fix

// before: assuming the file is always readable
String[] lines = TextFileInputHelper.getFirst(log, meta, 100, transMeta, null);
// after: guard existence first
FileObject f = KettleVFS.getFileObject(meta.getFileName(transMeta), transMeta);
if (!f.exists()) { throw new KettleFileException("File not found: " + f.getName().getURI()); }
String[] lines = TextFileInputHelper.getFirst(log, meta, 100, transMeta, null);
Defensive patterns

Strategy: validation

Validate before calling

FileObject f = KettleVFS.getFileObject(filename, transMeta);
if (!f.exists() || !f.isReadable()) {
  throw new KettleFileException("Cannot read file: " + f.getName().getURI());
}

Type guard

if (meta == null || meta.inputFiles == null || meta.inputFiles.fileName == null || meta.inputFiles.fileName.length == 0) return false; // file config not ready for getFirst

Try / catch

try {
  String[] lines = TextFileInputHelper.getFirst(log, meta, 100, transMeta, null);
} catch (KettleException e) {
  log.logError("Preview failed for " + e.getCause(), e);
  // fall back to manual line reading or abort preview
}

Prevention

When it happens

Trigger: Calling TextFileInputHelper.getFirst(...) (directly or via rows()/content()) when the file cannot be opened or read: missing file, bad VFS URI, wrong encoding, or an IOException/RuntimeException thrown inside skipHeaderLines/readFileLines.

Common situations: Previewing a CSV in Spoon whose file was moved or deleted; a VFS URI with typos (sftp://, s3:// credentials missing); a file with an encoding different from the one configured causing decode exceptions.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/fileinput/text/TextFileInputHelper.java:333

    StringBuilder lineStringBuilder = new StringBuilder( 256 );
    try ( InputStream fi = KettleVFS.getInputStream( file ) ) {
      CompressionProvider provider = CompressionProviderFactory.getInstance()
        .createCompressionProviderInstance( meta.content.fileCompression );
      f = provider.createInputStream( fi );
      try (BufferedInputStreamReader reader =
             (meta.getEncoding() != null && !meta.getEncoding().isEmpty())
               ? new BufferedInputStreamReader(new InputStreamReader(f, meta.getEncoding()))
               : new BufferedInputStreamReader(new InputStreamReader(f))) {

        EncodingType encodingType = EncodingType.guessEncodingType(reader.getEncoding());
        int maxnr = nrlines + (meta.content.header ? meta.content.nrHeaderLines : 0);
        if (skipHeaders) {
          skipHeaderLines(meta, reader, encodingType, lineStringBuilder);
        }
        readFileLines(meta, retval, reader, encodingType, nrlines, maxnr, lineStringBuilder);
      }
    } catch ( Exception e ) {
      throw new KettleException(
        BaseMessages.getString( PKG, "TextFileInputDialog.Exception.ErrorGettingFirstLines", "" + nrlines,
          file.getName().getURI() ), e );
    } finally {
      try {
        if ( f != null ) {
          f.close();
        }
      } catch ( Exception e ) {
        // Ignore errors
      }
    }

    return retval;
  }

  /**
   * Skips the required header lines if present.
   */

View on GitHub (pinned to f3058517a1)