pentaho/pentaho-kettle · error · KettleException

Please specify a filename before saving messages store for…

Error message

Please specify a filename before saving messages store for package '

What it means

MessagesStore.write() requires a filename to have been assigned before saving. If the store was created without a file (e.g. built in memory by the Translator) and write() is called without first calling write(String filename) or findFile(), this guard throws. It is an explicit pre-condition check to prevent silently discarding translations.

Solutions

1. Call write( String filename ) with an explicit target path instead of the no-arg write().
2. Call findFile()/getLoadFilename() first so the store gets a resolved filename, then save.
3. In UI code, ensure the save action only runs after 'Save As' assigned a filename.

Example fix

// before
store.write(); // filename == null -> KettleException

// after
if ( store.getFilename() == null ) {
  store.write( "/path/to/messages/messages_en_US.properties" );
} else {
  store.write();
}

if ( store.getFilename() == null ) {
  throw new IllegalStateException( "Assign a filename (write(path)) before saving" );
}
store.write();

try {
  store.write();
} catch ( KettleException e ) {
  if ( e.getMessage().startsWith( "Please specify a filename" ) ) {
    store.write( promptUserForSaveAsPath() );
  } else { throw e; }
}

When it happens

Trigger: Calling the no-argument write() on a MessagesStore whose filename field is still null — i.e. a store constructed manually or loaded without resolving a file via getLoadFilename/findFile.

Common situations: Programmatic use of MessagesStore (scripts/plugins around the Translator) that builds a store and saves it before a filename was ever set; Translator tool edge cases where no file could be located for the locale.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• " + element.getName() + " has a null id
• ERROR_0003_Cannot_Save_Job_Entry
• ERROR_0003_Cannot_Save_Job_Entry
• ERROR_0003_Cannot_Save_Job_Entry
• ERROR_0003_Unable_To_Save_Job

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

Appendix: source

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

      }
      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() ) {
          parent.mkdirs(); // create the messages/ folder
        }
      }
      Properties properties = new Properties();
      for ( String key : messagesMap.keySet() ) {
        properties.put( key, messagesMap.get( key ) );
      }

View on GitHub (pinned to f3058517a1)