pentaho/pentaho-kettle · error · KettleXMLException

TransMeta.Exception.MissingXMLFilePath

Error message

TransMeta.Exception.MissingXMLFilePath

What it means

A KettleXMLException (message key TransMeta.Exception.MissingXMLFilePath) thrown by the TransMeta(Bowl, fname, ...) constructor when the filename argument is blank. Without a file path there is nothing to load, so the constructor fails fast before any VFS access.

Solutions

  1. Pass a valid, non-blank path to the .ktr file
  2. Validate the filename before constructing TransMeta (StringUtils.isBlank check)
  3. If loading from a repository, use the repository-based TransMeta constructor instead
  4. Trace where fname comes from and fix the upstream resolution

Example fix

// before
TransMeta tm = new TransMeta(bowl, config.getProperty("trans.path"), metaStore, null, true, vars, null);
// after
String fname = config.getProperty("trans.path");
if (StringUtils.isBlank(fname)) throw new IllegalArgumentException("trans.path is required");
TransMeta tm = new TransMeta(bowl, fname, metaStore, null, true, vars, null);
Defensive patterns

Strategy: validation

Validate before calling

if (fname == null || fname.isBlank()) throw new IllegalArgumentException("Transformation file path must be provided");

Try / catch

try { new TransMeta(bowl, fname, metaStore, rep, true, vars, prompter); } catch (KettleXMLException e) { log.error("Missing/invalid trans file path", e); }

Prevention

When it happens

Trigger: new TransMeta(bowl, null, metaStore, rep, true, parentSpace, prompter) or fname = "" / whitespace-only.

Common situations: Path variables resolved from env/properties that are unset; callers passing the wrong argument (null filename with a repository instead); dynamic path building producing an empty string.

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

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/TransMeta.java:3058

   * @param rep
   *          The repository to load the default set of connections from, null if no repository is available
   * @param setInternalVariables
   *          true if you want to set the internal variables based on this transformation information
   * @param parentVariableSpace
   *          the parent variable space to use during TransMeta construction
   * @param prompter
   *          the changed/replace listener or null if there is none
   * @throws KettleXMLException
   *           if any errors occur during parsing of the specified file
   * @throws KettleMissingPluginsException
   *           in case missing plugins were found (details are in the exception in that case)
   */
  public TransMeta( Bowl bowl, String fname, IMetaStore metaStore, Repository rep, boolean setInternalVariables,
                    VariableSpace parentVariableSpace, OverwritePrompter prompter )
    throws KettleXMLException, KettleMissingPluginsException {
    // if fname is not provided, there's not much we can do, throw an exception
    if ( StringUtils.isBlank( fname ) ) {
      throw new KettleXMLException( BaseMessages.getString( PKG, "TransMeta.Exception.MissingXMLFilePath" ) );
    }
    this.metaStore = metaStore;
    this.repository = rep;

    // OK, try to load using the VFS stuff...
    Document doc = null;
    try {
      // start by inheriting the bowl from the argument. It might get overwritten later. 
      if ( bowl != null ) {
        setBowl( bowl );
      }
      if ( parentVariableSpace == null ) {
        parentVariableSpace = new Variables();
        // load globals
        parentVariableSpace.initializeVariablesFrom( null );
      }

      final FileObject transFile = KettleVFS.getInstance( bowl ).getFileObject( fname, parentVariableSpace );

View on GitHub (pinned to f3058517a1)