pentaho/pentaho-kettle · error · KettleXMLException

XMLHandler.errorCheckingFileExistence

XMLHandler.errorCheckingFileExistence

Error message

${XMLHandler.errorCheckingFileExistence}

What it means

checkFile(FileObject) returns whether the FileObject exists and is a file; if the VFS layer itself fails during the exists()/isFile() probe (FileSystemException), it throws KettleXMLException with the localized message XMLHandler.errorCheckingFileExistence including the file path. It distinguishes 'cannot even check' from 'file absent'.

Solutions

1. Inspect the chained FileSystemException for the provider-level error; test the URI with the standalone VFS/CLI tool.
2. Validate the VFS URI scheme and syntax (e.g. sftp://user:host/path vs correct sftp://host/path).
3. Check network connectivity and credentials for remote filesystems.
4. Treat checkFile failure as 'unknown state' and retry with backoff for transient network problems.

Example fix

// before
boolean ok = XMLHandler.checkFile(KettleVFS.getFileObject(uri));
// after
boolean ok;
try {
  ok = XMLHandler.checkFile(KettleVFS.getFileObject(uri));
} catch (KettleXMLException e) {
  log.warn("Cannot verify " + uri + ": " + e.getCause());
  ok = false;
}

try { fo.exists(); } catch (FileSystemException e) { /* VFS provider broken — fix URI/network first */ }

boolean canProbe(FileObject fo) {
  try { fo.exists(); return true; } catch (FileSystemException e) { return false; }
}

try {
  ok = XMLHandler.checkFile(fo);
} catch (KettleXMLException e) {
  log.warn("Cannot verify file " + fo + ": " + e.getCause());
  ok = false; // unknown state, treat as missing
}

When it happens

Trigger: XMLHandler.checkFile(FileObject) where fileObject.exists() or isFile() throws FileSystemException: unreachable remote filesystem (SFTP/HTTP VFS provider), invalid URI scheme, closed/broken VFS manager, permission issues at the provider level.

Common situations: Remote VFS endpoints (SFTP host down, expired credentials), invalid VFS URIs (sftp:// with wrong syntax), network partitions during job startup, VFS plugins missing.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Error opening new file
• The function call getFileExtension throw an error :
• The function call getLastModifiedTime throw an error :
• The function call getParentFoldername throw an error :
• The function call getShortFilename throw an error :

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

Appendix: source

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

      t.transform( new DOMSource( node ), new StreamResult( sw ) );
    } catch ( Exception e ) {
      throw new KettleXMLException( "Unable to format Node as XML", e );
    }
    return sw.toString();
  }

  /**
   * <p>Checks if a given {@link FileObject} instance corresponds to an existing file.</p>
   *
   * @param fileObject the {@link FileObject} instance to check
   * @return <code>true</code> if the file exists, <code>false</code> otherwise
   * @throws KettleXMLException if an error occurred while checking
   */
  public static boolean checkFile( FileObject fileObject ) throws KettleXMLException {
    try {
      return fileObject != null && fileObject.exists() && fileObject.isFile();
    } catch ( FileSystemException e ) {
      throw new KettleXMLException( BaseMessages.getString(
        PKG, "XMLHandler.errorCheckingFileExistence", fileObject.toString() ), e );
    }
  }
}

/**
 * Handle external references and return an empty dummy document.
 *
 * @author jb
 * @since 2007-12-21
 */
class DTDIgnoringEntityResolver implements EntityResolver {
  private static final Log log = LogFactory.getLog( DTDIgnoringEntityResolver.class );
  @Override
  public InputSource resolveEntity( String publicID, String systemID ) throws IOException {
    log.info( "Public-ID: " + publicID );
    log.info( "System-ID: " + systemID );
    return new InputSource( new ByteArrayInputStream( "<?xml version='1.0' encoding='UTF-8'?>".getBytes() ) );

View on GitHub (pinned to f3058517a1)