pentaho/pentaho-kettle · error · KettleFileException

Couldn't write to the database cache

Error message

Couldn't write to the database cache

What it means

saveCache() wraps its entire write in a catch-all: after opening the file, writing entries, or throwing the earlier specific errors, any resulting Exception is re-thrown as KettleFileException 'Couldn't write to the database cache' with the original as cause. It is the generic failure path for persisting the DB cache to disk.

Solutions

  1. Check the wrapped cause (getCause()) — usually an IOException; verify disk space and file availability
  2. Make the cache write non-fatal for your use case (log and continue; the cache is an optimization)
  3. Delete the cache file and let it rebuild; ensure only one Kettle process writes it

Example fix

// before
DBCache.getInstance().savesCacheToDisk(); // RuntimeException on IO failure
// after
try {
  DBCache.getInstance().savesCacheToDisk();
} catch (KettleFileException e) {
  log.logMinimal("DB cache write skipped: " + e.getMessage()); // cache is optional
}
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check disk space and writability before saving
File f = new File(cacheFile); if (f.getParentFile().getUsableSpace() < MIN_FREE) { skipSave(); }

Try / catch

try { cache.savesCacheToDisk(); } catch (KettleFileException e) { Throwable cause = e.getCause(); log.warn("DB cache write failed: " + (cause != null ? cause.getMessage() : e.getMessage())); }

Prevention

When it happens

Trigger: IOException while writing cache entries to the open DataOutputStream (disk full, stream closed, file handle lost), or any of the inner specific KettleFileExceptions (empty row / non-writable file) being caught and re-wrapped by the outer catch.

Common situations: Disk full on the drive holding the cache file; file deleted/unlocked mid-write by another process; antivirus or backup software interfering with the cache file.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

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

Appendix: source

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

          for ( DBCacheEntry entry : cache.keySet() ) {
            entry.write( dos );

            // Save the corresponding row as well.
            RowMetaInterface rowMeta = get( entry );
            if ( rowMeta != null ) {
              rowMeta.writeMeta( dos );
              counter++;
            } else {
              throw new KettleFileException( "The database cache contains an empty row. We can't save this!" );
            }
          }
          log.logDetailed( "We wrote " + counter + " cached rows to the database cache!" );
        }
      } else {
        throw new KettleFileException( "We can't write to the cache file: " + filename );
      }
    } 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() );
    }

View on GitHub (pinned to f3058517a1)