pentaho/pentaho-kettle · error · KettleException

Error opening DBF metadata

Error message

Error opening DBF metadata

What it means

XBase.open() opens the .dbf file and constructs a DBFReader. A DBFException from the JavaDBF reader (structurally invalid DBF header/records) is wrapped as 'Error opening DBF metadata'. This distinguishes a corrupt/invalid DBF format problem from a plain I/O problem (which produces 'Error reading DBF file').

Solutions

1. Verify the file is a genuine DBF: check the first bytes (valid dBASE files start with a version byte, e.g. 0x03/0x30) and open it in a DBF viewer.
2. Re-export or re-download the DBF file; ensure the transfer was not ASCII-mangled (use binary mode).
3. Confirm the dbfFile path points to the intended file, not a companion .dbt memo or an unrelated file.
4. If the file comes from another system, save it with a compatible dBASE III/IV format before use.

Example fix

// before
String dbfFile = "/data/export.csv"; // wrong file supplied
// after
String dbfFile = "/data/export.dbf"; // actual dBASE file

File f = new File(dbfFile);
if (!f.isFile() || f.length() < 33) {
  throw new IllegalArgumentException("Not a plausible DBF file: " + dbfFile);
}
int versionByte = new java.io.RandomAccessFile(f, "r").read(); // expect 0x03/0x30 etc.
if (versionByte == 'C' || versionByte == '{') { throw new IllegalArgumentException("File is not dBASE format"); }

try {
  xbase.open();
} catch (KettleException e) {
  if (e.getMessage().contains("Error opening DBF metadata")) {
    // file is not valid DBF: re-export or repair before retry
  }
}

When it happens

Trigger: Calling open() — directly or via getOutputFields(), check(), getFields(), readFile() — when new DBFReader(inputstream) throws DBFException because the stream does not contain a valid DBF file structure.

Common situations: Pointing the step at a file with .dbf extension that is actually CSV/text; truncated or corrupted DBF download; DBF saved by a tool using an unsupported dBASE variant; zero-byte file.

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

• Error parsing field #
• Error reading DBF file
• Error reading DBF metadata (in part
• TextFileInput.Log.SingleLineFound
• TextFileInput.Log.SingleLineFound

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/xbaseinput/XBase.java:79

    inputstream = null;
  }

  public XBase( LogChannelInterface log, InputStream inputStream ) {
    this.log = log;
    this.dbfFile = null;
    this.error = false;
    this.reader = null;
    this.inputstream = inputStream;
  }

  public void open() throws KettleException {
    try {
      if ( inputstream == null ) {
        inputstream = new FileInputStream( dbfFile );
      }
      reader = new DBFReader( inputstream );
    } catch ( DBFException e ) {
      throw new KettleException( "Error opening DBF metadata", e );
    } catch ( IOException e ) {
      throw new KettleException( "Error reading DBF file", e );
    }
  }

  @SuppressWarnings( "fallthrough" )
  public RowMetaInterface getFields() throws KettleException {
    String debug = "get fields from XBase file";
    RowMetaInterface row = new RowMeta();

    try {
      // Fetch all field information
      //
      debug = "allocate data types";
      datatype = new byte[reader.getFieldCount()];

      for ( int i = 0; i < reader.getFieldCount(); i++ ) {
        if ( log.isDebug() ) {

View on GitHub (pinned to f3058517a1)