pentaho/pentaho-kettle · error · KettleException

Unable to save messages properties file '

Error message

Unable to save messages properties file '

What it means

MessagesStore.write(String filename) wraps any IOException encountered while writing the properties file (creating the output stream, storing properties, closing) into a KettleException with the target filename. This is a low-level I/O failure, not a logic error: disk, path, or permission problems.

Solutions

  1. Verify the parent directory of filename exists and is writable; create it if needed.
  2. Check file/directory permissions and that no other process locks the file.
  3. Check free disk space.
  4. Run the Translator with a working directory / source folder that is writable.

Example fix

// before
store.write( "/opt/pentaho/design-tools/translator/src/org/pentaho/di/messages/messages_fr.properties" );

// after
File out = new File( targetPath );
File parent = out.getParentFile();
if ( !parent.exists() ) parent.mkdirs();
if ( !parent.canWrite() ) throw new IllegalStateException( "Not writable: " + parent );
store.write( out.getAbsolutePath() );
Defensive patterns

Strategy: try-catch

Validate before calling

File out = new File( filename );
File parent = out.getParentFile();
if ( parent == null || !parent.isDirectory() || !parent.canWrite() ) {
  throw new IllegalStateException( "Target dir missing or not writable: " + parent );
}

Try / catch

try {
  store.write( filename );
} catch ( KettleException e ) {
  log.error( "Could not write " + filename + ": check permissions, disk space, locks", e );
}

Prevention

When it happens

Trigger: The target directory does not exist, the process lacks write permission, the file is locked by another process, or the disk is full when properties.store() writes the file.

Common situations: Saving translations into a read-only source tree (e.g. inside a jar'ed module or version-controlled folder checked out read-only); saving to a path on a disconnected drive; concurrent Translator sessions holding the 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/6213a68ba14fe0ca. Report an issue: GitHub.

Appendix: source

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

      if ( !file.exists() ) {
        File parent = file.getParentFile();
        if ( !parent.exists() ) {
          parent.mkdirs(); // create the messages/ folder
        }
      }
      Properties properties = new Properties();
      for ( String key : messagesMap.keySet() ) {
        properties.put( key, messagesMap.get( key ) );
      }
      FileOutputStream fileOutputStream = new FileOutputStream( file );
      String comment =
        "File generated by Pentaho Translator for package '"
          + messagesPackage + "' in locale '" + locale + "'" + Const.CR + Const.CR;
      properties.store( fileOutputStream, comment );
      fileOutputStream.close();
      setChanged( false );
    } catch ( IOException e ) {
      throw new KettleException( "Unable to save messages properties file '" + filename + "'", e );
    }
  }

  /**
   * Find a suitable filename for the specified locale and messages package. It tries to find the file in the specified
   * directories in the order that they are specified.
   *
   * @param alternativeSourceFolders
   *
   * @param directories
   *          the source directories to try and map the messages files against.
   * @return the filename that was found.
   */
  public String getLoadFilename( List<String> alternativeSourceFolders ) throws FileNotFoundException {
    String path = calcFolderName( sourceFolder );

    // First try the source folder of the Java file
    //

View on GitHub (pinned to f3058517a1)