What causes "We can't write to the cache file: " in pentaho/pentaho-kettle?

Verify the cache file's directory exists and the process user has write permission; chmod/chown or move KETTLE home to a writable location

pentaho/pentaho-kettle · error · KettleFileException

We can't write to the cache file:

Error message

We can't write to the cache file:

What it means

saveCache() first creates/opens the cache file for writing; if the file object is not writable (doesn't exist and can't be created, or is read-only) it throws KettleFileException 'We can't write to the cache file: <filename>', naming the file. This happens before any cache content is serialized.

Solutions

Verify the cache file's directory exists and the process user has write permission; chmod/chown or move KETTLE home to a writable location
Close other running Kettle instances or delete stale locks on db.cache
Disable the DB cache (e.g. KETTLE_CURSOR / cache size 0 options) if the environment must be read-only

Example fix

// before
File cache = new File(filename); // in read-only dir
saveCache();
// after
File f = new File(filename);
if (!f.canWrite()) { log.logBasic("Skipping DB cache write, file not writable: " + filename); return; }
saveCache();

Defensive patterns

Strategy: validation

Validate before calling

File f = new File(cacheFile);
File dir = f.getParentFile();
boolean ok = dir != null && dir.isDirectory() && dir.canWrite() && (!f.exists() || f.canWrite());
if (!ok) { /* skip cache write or fix permissions */ }

Try / catch

try { cache.savesCacheToDisk(); } catch (KettleFileException e) { if (e.getMessage().contains("can't write to the cache file")) { log.warn("Cache file not writable: " + e.getMessage()); } else { throw e; } }

Prevention

Ensure the Kettle home/system directory is writable by the service user
Avoid running multiple Kettle instances sharing one cache file
Point KETTLE_HOME to a writable location on read-only installs
Consider disabling the DB cache in read-only environments

When it happens

Trigger: Calling savesCacheToDisk()/saveCache() when the cache file path exists but is not writable, the parent directory doesn't exist, or the file is locked by another process.

Common situations: Read-only Kettle installation directory or KETTLE_SYSTEM_DIR; running multiple Kettle instances concurrently locking db.cache; running under a service account lacking write permissions to the cache folder.

Understand the failure class

Background: "Permission denied" / "Failed to write" file errors: why a library can't write its files to disk (EACCES, EPERM, ENOSPC) and how to fix them — this error's family across 43 libraries.

Related errors

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

Appendix: source

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

          int counter = 0;

          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();

View on GitHub (pinned to f3058517a1)