pentaho/pentaho-kettle · error · RuntimeException

Unable to create the database cache:

Error message

Unable to create the database cache: 

What it means

DBCache.getInstance() lazily creates the singleton DBCache; the constructor may throw KettleFileException (e.g. corrupt cache file). getInstance converts this into a RuntimeException 'Unable to create the database cache: <message>' because a static factory cannot declare checked exceptions. Callers see an unchecked failure whenever the cache cannot be initialized from disk.

Solutions

1. Delete the corrupt db.cache file so a fresh one is created on next startup
2. Wrap the first getInstance() call in try-catch and degrade gracefully (run without the DB cache)
3. Check that the Kettle system/user directory is readable by the process user

Example fix

// before
DBCache dbCache = DBCache.getInstance(); // RuntimeException if cache corrupt
// after
DBCache dbCache;
try { dbCache = DBCache.getInstance(); }
catch (RuntimeException e) { log.logError("DB cache unavailable, continuing without it: " + e.getMessage()); dbCache = null; }

File cacheFile = new File(cachePath);
if (cacheFile.exists() && !cacheFile.canRead()) { cacheFile.delete(); } // rebuild on first use

try { DBCache dbCache = DBCache.getInstance(); } catch (RuntimeException e) { log.error("DB cache init failed: " + e.getMessage()); /* proceed without cache or rethrow */ }

When it happens

Trigger: First call to DBCache.getInstance() in a JVM where the persisted db.cache file is unreadable/corrupt (see error 85), causing the constructor's KettleFileException to be re-thrown as RuntimeException.

Common situations: Upgraded Kettle reading an old-format db.cache; corrupted cache file after a crash; read-permission issues on the cache file at first use of the database cache.

Related errors

• Couldn't read 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/983e5cf73a7cef6a. Report an issue: GitHub.

Appendix: source

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

    } catch ( Exception e ) {
      throw new KettleFileException( "Couldn't write to the database cache", e );
    }
  }

  /**
   * Create the database cache instance by loading it from disk
   *
   * @return the database cache instance.
   */
  @SuppressWarnings( "squid:S00112" )
  public static DBCache getInstance() {
    if ( dbCache != null ) {
      return dbCache;
    }
    try {
      dbCache = new DBCache();
    } catch ( KettleFileException kfe ) {
      throw new RuntimeException( "Unable to create the database cache: " + kfe.getMessage() );
    }
    return dbCache;
  }

}

View on GitHub (pinned to f3058517a1)