pentaho/pentaho-kettle · error · KettleStepException

Unable to read from DBF file

Error message

Unable to read from DBF file

What it means

ShapeFileReaderMeta.getFields reads the DBF (attribute) file with an XBase reader to derive output row fields; any Throwable while opening/reading it is wrapped in 'Unable to read from DBF file'. It signals that the field layout could not be determined because the DBF file could not be accessed or parsed.

Solutions

1. Verify the DBF filename field points to an existing, readable .dbf file that accompanies the .shp.
2. Copy all shapefile sidecar files (.shp, .shx, .dbf) together.
3. Check file permissions and that no other process holds an exclusive lock on the .dbf.
4. Inspect the wrapped cause 'e' in the stack trace for the precise I/O or parse failure.

Example fix

// before
String dbf = "/data/roads.dbf"; // file does not exist
// after
File f = new File( "/data/roads.dbf" );
if ( !f.exists() ) throw new KettleException( "DBF missing: " + f );
String dbf = f.getAbsolutePath();

File dbf = new File( dbfFilename );
if ( !dbf.isFile() || !dbf.canRead() ) {
  throw new KettleException( "DBF file missing or unreadable: " + dbfFilename );
}

try {
  meta.getFields( row, name, info, null, null, repository );
} catch ( KettleStepException e ) {
  logError( "DBF read failed: " + e.getCause(), e );
}

When it happens

Trigger: getFields is called (e.g. during step preview or transformation layout resolution) and the XBase reader throws while opening or reading the .dbf at the configured dbfFilename — missing file, wrong path, corrupt header, or unsupported encoding.

Common situations: The .dbf path was moved or renamed, the shapefile was copied without its sidecar files, the file is locked by another process, or the file is not actually a dBase/DBF 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

• Unable to read from DBF file: no filename specfied
• AvroInputDialog.Error.KettleFileException
• context.getMessage()
• Error during processing a row
• Error opening DBF metadata

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

Appendix: source

Thrown at plugins/shapefilereader/core/src/main/java/org/pentaho/di/shapefilereader/ShapeFileReaderMeta.java:233

      XBase xbase = new XBase( getLog(), dbFilename );
      try {
        xbase.setDbfFile( dbFilename );
        xbase.open();

        //Set encoding
        if ( StringUtils.isNotBlank( encoding ) ) {
          xbase.getReader().setCharactersetName( encoding );
        }

        RowMetaInterface fields = xbase.getFields();
        for ( int i = 0; i < fields.size(); i++ ) {
          fields.getValueMeta( i ).setOrigin( name );
          row.addValueMeta( fields.getValueMeta( i ) );
        }

      } catch ( Throwable e ) {
        throw new KettleStepException( "Unable to read from DBF file", e );
      } finally {
        xbase.close();
      }
    } else {
      throw new KettleStepException( "Unable to read from DBF file: no filename specfied" );
    }
  }

  public String getXML() {
    String retval = "";

    retval += "    " + XMLHandler.addTagValue( "shapefilename", shapeFilename );
    retval += "    " + XMLHandler.addTagValue( "dbffilename", dbfFilename );
    retval += "    " + XMLHandler.addTagValue( "encoding", encoding );

    return retval;
  }

View on GitHub (pinned to f3058517a1)