pentaho/pentaho-kettle · error · KettleFileException

Couldn't read the database cache

Error message

Couldn't read the database cache

What it means

DBCache.getInstance()/constructor loads a persisted database-prepared-statements cache file from disk; if reading or decoding the cache file fails at any point, the load is wrapped in KettleFileException 'Couldn't read the database cache'. The constructor throws, so getInstance converts it to a RuntimeException 'Unable to create the database cache'.

Solutions

1. Delete/rename the corrupt cache file (db.cache) and let Kettle rebuild it — the cache is purely an optimization
2. Check file read permissions and disk health for the cache file's directory
3. If it happens after an upgrade, it's a format-version mismatch; the cache file is not portable between versions

Example fix

// before
DBCache dbCache = DBCache.getInstance(); // RuntimeException: Couldn't read the database cache
// after
File cache = new File(System.getProperty("KETTLE_HOME"), "db.cache");
if (cache.exists() && cache.length() == 0) { cache.delete(); }
DBCache dbCache = DBCache.getInstance();

File cacheFile = new File(cachePath);
if (cacheFile.exists() && (cacheFile.length() == 0 || !cacheFile.canRead())) { cacheFile.delete(); }

try { DBCache dbCache = DBCache.getInstance(); } catch (RuntimeException e) { log.warn("DB cache unavailable: " + e.getMessage()); /* continue without cache */ }

When it happens

Trigger: Constructing DBCache when the cache file (db.cache in the Kettle local/system folder) exists but is unreadable: corrupt/truncated file, wrong format version, or I/O error during DataInputStream read of the header or entries.

Common situations: Leftover db.cache from an older Kettle version after an upgrade; disk corruption or crash during a previous cache write; read-permission problems on the cache 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 create the database cache:
• Couldn't write to the database cache
• The database cache contains an empty row. We can't save…
• We can't write to the cache file:
• AccessInput.Error.ErrorReadingFile

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/DBCache.java:150

      clear( null );

      // Serialization support for the DB cache
      //
      log = new LogChannel( "DBCache" );

      String filename = fileNameSupplier.get();
      File file = new File( filename );
      if ( file.canRead() ) {
        log.logDetailed( "Loading database cache from file: [" + filename + "]" );

        try ( DataInputStream dis = new DataInputStream( new FileInputStream( file ) ) ) {
          loadFileToCache( dis );
        }
      } else {
        log.logDetailed( "The database cache doesn't exist yet." );
      }
    } catch ( Exception e ) {
      throw new KettleFileException( "Couldn't read the database cache", e );
    }
  }

  @SuppressWarnings( { "squid:S2189", "squid:S1451" } )
  private void loadFileToCache( DataInputStream dis ) throws KettleFileException, SocketTimeoutException {
    int counter = 0;
    try {
      //noinspection InfiniteLoopStatement Only way to detect EOF on DataInputStream is with exception
      while ( true ) {
        DBCacheEntry entry = new DBCacheEntry( dis );
        RowMetaInterface row = new RowMeta( dis );
        cache.put( entry, row );
        counter++;
      }
    } catch ( KettleEOFException eof ) {
      log.logDetailed( "We read " + counter + " cached rows from the database cache!" );
    }
  }

View on GitHub (pinned to f3058517a1)