pentaho/pentaho-kettle · error · KettleXMLException

XMLHandler.FileDoesNotExists

XMLHandler.FileDoesNotExists

Error message

${XMLHandler.FileDoesNotExists}

What it means

loadXMLFile throws this KettleXMLException when the supplied file (a KettleVFS FileObject) does not exist on disk. The library checks existence before attempting XML parsing and fails fast with a localized message that includes the file path. It signals a path/configuration problem, not a parse problem.

Solutions

  1. Verify the file path exists before calling loadXMLFile (new File(path).exists() or FileObject.exists()).
  2. Convert relative paths to absolute against $PWD or KETTLE_HOME; on Linux check case sensitivity.
  3. Ensure the resource file is deployed/packaged alongside the job or transformation.
  4. If loading from the classpath instead, use loadXMLFile(InputStream) or loadXMLFile(URL).

Example fix

// before
Document doc = XMLHandler.loadXMLFile(KettleVFS.getFileObject("conf/job.xml"));
// after
FileObject fo = KettleVFS.getFileObject("conf/job.xml");
if (fo == null || !fo.exists() || !fo.isFile()) {
  throw new KettleException("Missing XML file: " + fo);
}
Document doc = XMLHandler.loadXMLFile(fo);
Defensive patterns

Strategy: validation

Validate before calling

FileObject fo = KettleVFS.getFileObject(path);
if (fo == null || !fo.exists() || !fo.isFile()) {
  throw new KettleException("XML file missing: " + path);
}

Type guard

boolean isLoadable(FileObject fo) {
  try { return fo != null && fo.exists() && fo.isFile(); }
  catch (FileSystemException e) { return false; }
}

Try / catch

try {
  Document doc = XMLHandler.loadXMLFile(fo);
} catch (KettleXMLException e) {
  throw new KettleException("Config XML not found: " + fo, e);
}

Prevention

When it happens

Trigger: Calling XMLHandler.loadXMLFile(FileObject) with a fileObject where fileObject.exists() returns false (or is not a file). The message is filled with fileObject.toString().

Common situations: Typos in kettle.properties-referenced file paths, relative paths resolved against the wrong working directory, files deleted between check and load, deploying jobs/transformation resources that reference missing XML files, case-sensitive filesystems on Linux.

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

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/xml/XMLHandler.java:618

        try {
          return loadXMLFile( KettleVFS.getInputStream( fileObject ), systemID, ignoreEntities, namespaceAware );
        } catch ( Exception ex ) {
          lastException = ex;
          try {
            java.lang.Thread.sleep( 1000 );
          } catch ( InterruptedException e ) {
            //Sonar squid S2142 requires the handling of the InterruptedException instead of ignoring it
            Thread.currentThread().interrupt();
          }
        }
        attempts++;
      }

      throw new KettleXMLException( BaseMessages.getString(
        PKG, "XMLHandler.errorReadingFile", fileObject.toString() ), lastException );
    }

    throw new KettleXMLException( BaseMessages.getString(
      PKG, "XMLHandler.FileDoesNotExists", fileObject.toString() ) );
  }

  /**
   * Read in an XML file from the passed input stream and return an XML document
   *
   * @param inputStream The filename input stream to read the document from
   * @return the Document if all went well, null if an error occurred!
   */
  public static Document loadXMLFile( InputStream inputStream ) throws KettleXMLException {
    return loadXMLFile( inputStream, null, false, false );
  }

  /**
   * Load a file into an XML document
   *
   * @param inputStream    The stream to load a document from
   * @param systemID       Provide a base for resolving relative URIs.

View on GitHub (pinned to f3058517a1)