pentaho/pentaho-kettle · error · KettleStepException

XBaseInputMeta.Exception.UnableToReadMetaDataFromXBaseFile

Error message

XBaseInputMeta.Exception.UnableToReadMetaDataFromXBaseFile

What it means

Thrown by XBaseInputMeta.getOutputFields() when opening the XBase file(s) to derive the output RowMeta fails for any reason. The step needs the DBF structure (field names/types) to build output row metadata; if reading that metadata fails, a KettleStepException with this message is raised. The XBaseInput instance is closed in finally regardless.

Solutions

1. Verify the configured .dbf file path exists and is readable by the Pentaho user.
2. Open the DBF in a dBase viewer to confirm it has a valid header/field definitions.
3. Fix the encoding selection in the XBase Input dialog if the file uses a non-default code page.
4. Check the chained cause (KettleStepException.getCause()) for the underlying open/read failure.
5. When using 'accept filenames from previous step', confirm the upstream step actually produces the filename rows at design time.

Example fix

// before: file configured but missing at runtime
filename = "C:\\data\\customers.dbf"; // file no longer exists

// after: ensure path is valid before running the transformation
File f = new File( "C:\\data\\customers.dbf" );
if ( !f.isFile() || !f.canRead() ) {
  throw new KettleStepException( "DBF file missing or unreadable: " + f.getAbsolutePath() );
}

File dbf = new File( configuredPath );
if ( !dbf.isFile() || !dbf.canRead() || dbf.length() == 0 ) {
  throw new KettleStepException( "Cannot read DBF metadata; file invalid: " + configuredPath );
}

try {
  meta.getFields( ... );
} catch ( KettleStepException e ) {
  logError( "XBase metadata read failed: " + e.getCause(), e );
  // abort or fall back to a known-good schema definition
}

When it happens

Trigger: getFields() -> getOutputFields() opens the DBF file to read its schema; any exception there (file missing, unreadable, corrupt header, bad encoding) is wrapped with this message before being rethrown as KettleStepException.

Common situations: Typo in file path or filename from previous step, file deleted/moved after configuring the step, non-DBF file with .dbf extension, insufficient read permissions, wrong encoding setting.

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

• Unable to read row from XBase file
• Error reading DBF metadata (in part
• ERROR_0018_META_REPOSITORY_NOT_POPULATED
• Error evaluating timestamp value metadata
• Error opening DBF metadata

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/xbaseinput/XBaseInputMeta.java:318

  public RowMetaInterface getOutputFields( FileInputList files, String name ) throws KettleStepException {
    RowMetaInterface rowMeta = new RowMeta();

    // Take the first file to determine what the layout is...
    //
    XBase xbi = null;
    try {
      xbi = new XBase( getLog(), KettleVFS.getInputStream( files.getFile( 0 ) ) );
      xbi.setDbfFile( files.getFile( 0 ).getName().getURI() );
      xbi.open();
      RowMetaInterface add = xbi.getFields();
      for ( int i = 0; i < add.size(); i++ ) {
        ValueMetaInterface v = add.getValueMeta( i );
        v.setOrigin( name );
      }
      rowMeta.addRowMeta( add );
    } catch ( Exception ke ) {
      throw new KettleStepException( BaseMessages.getString(
        PKG, "XBaseInputMeta.Exception.UnableToReadMetaDataFromXBaseFile" ), ke );
    } finally {
      if ( xbi != null ) {
        xbi.close();
      }
    }

    if ( rowNrAdded && rowNrField != null && rowNrField.length() > 0 ) {
      ValueMetaInterface rnr = new ValueMetaInteger( rowNrField );
      rnr.setOrigin( name );
      rowMeta.addValueMeta( rnr );
    }

    if ( includeFilename ) {
      ValueMetaInterface v = new ValueMetaString( filenameField );
      v.setLength( 100, -1 );
      v.setOrigin( name );
      rowMeta.addValueMeta( v );

View on GitHub (pinned to f3058517a1)