pentaho/pentaho-kettle · error · KettleException

Unable to read messages file for locale : '

Error message

Unable to read messages file for locale : '

What it means

MessagesStore.read() throws this when it cannot read a messages_<locale>.properties file for a given locale and messages package (used by the Pentaho Translator tool). It aggregates occurrences (key/file) into the message to pinpoint the bad file. Typically the underlying IOException/properties parse failure comes from a missing or malformed properties file.

Solutions

1. Check the keys= list in the message: open/verify each listed file exists and is readable at that path.
2. Confirm the locale string matches the filename pattern messages_<locale>.properties exactly.
3. Ensure the source folders configured for the store include the folder containing the file.
4. Validate the properties file syntax/encoding (ASCII with \u escapes or UTF-8 handled by the loader).

Example fix

// before
store.read(); // fails: messages_es_ES.properties missing in configured folders

// after
File expected = new File( sourceFolder + "/org/pentaho/di/messages/messages_" + locale + ".properties" );
if ( !expected.exists() ) {
  throw new IllegalStateException( "Missing messages file: " + expected.getAbsolutePath() );
}
store.read();

File f = new File( sourceFolder + "/" + messagesPackage.replace( '.', '/' ) + "/messages_" + locale + ".properties" );
if ( !f.isFile() ) throw new IllegalStateException( "Missing messages file: " + f );

try {
  store.read();
} catch ( KettleException e ) {
  log.error( "Check keys= list for the offending locale/package files: " + e.getMessage() );
}

When it happens

Trigger: read() is asked for a locale/package whose properties file does not exist in any source folder, is unreadable (permissions), or cannot be parsed as a properties file (bad encoding, invalid escapes).

Common situations: Editing translations in the Translator tool against a source folder where the expected messages file was renamed or moved; a locale variant (e.g. messages_es_ES.properties vs messages_es.properties) mismatch; files with wrong encoding after a git or editor change.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• package file could not be found for file in folder
• Unable to find properties file
• AccessInput.Error.ErrorReadingFile
• AvroInput.Error.ObjectReadError
• Could not apply local format for

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

Appendix: source

Thrown at ui/src/main/java/org/pentaho/di/ui/i18n/MessagesStore.java:111

      }
    } catch ( Exception e ) {
      String keys = "[";
      Map<String, List<KeyOccurrence>> po = sourcePackageOccurrences.get( sourceFolder );
      List<KeyOccurrence> keyList = po == null ? new ArrayList<KeyOccurrence>() : po.get( messagesPackage );
      if ( keyList == null ) {
        keyList = new ArrayList<KeyOccurrence>();
      }
      boolean first = true;
      for ( KeyOccurrence occ : keyList ) {
        if ( first ) {
          first = false;
        } else {
          keys += ", ";
        }
        keys += occ.getKey() + "/" + occ.getFileObject().toString();
      }
      keys += "]";
      throw new KettleException( "Unable to read messages file for locale : '"
        + locale + "' and package '" + messagesPackage + "', keys=" + keys, e );
    }
  }

  public void write() throws KettleException {
    if ( filename == null ) {
      throw new KettleException( "Please specify a filename before saving messages store for package '"
        + messagesPackage + "' and locale '" + locale + "" );
    }
    write( filename );
  }

  public void write( String filename ) throws KettleException {
    try {
      File file = new File( filename );
      if ( !file.exists() ) {
        File parent = file.getParentFile();
        if ( !parent.exists() ) {

View on GitHub (pinned to f3058517a1)