pentaho/pentaho-kettle · error · KettleStepException

XsdValidator.Exception.XSDFileNotExists

Error message

XsdValidator.Exception.XSDFileNotExists

What it means

KettleStepException thrown when the configured XSD filename resolves to a file that does not exist on the filesystem/VFS. The step checks xsdfile.exists() right after resolving the (environment-substituted) filename and aborts the row loop.

Solutions

  1. Verify the XSD file exists at the exact configured path on the machine running the transformation
  2. Check environment variables used in the filename resolve correctly (log environmentSubstitute output)
  3. Use an absolute path or correct the working directory when running via pan/Carte
  4. Add the schema to source control / shared storage and reference it with a stable path

Example fix

// before
String xsdPath = "${XSD_HOME}/order.xsd"; // XSD_HOME unset -> bad path
// after
String xsdPath = "/opt/pdi/schemas/order.xsd"; // or ensure XSD_HOME is exported
Defensive patterns

Strategy: validation

Validate before calling

String path = environmentSubstitute(meta.getXSDFilename());
if (path != null && !new File(path).exists()) { throw new IllegalStateException("XSD file not found: " + path); }

Try / catch

try { run(); } catch (KettleStepException e) { if (e.getMessage().contains("XSDFileNotExists")) { checkSchemaDeployment(); } else { throw e; } }

Prevention

When it happens

Trigger: KettleVFS.getFileObject(environmentSubstitute(meta.getXSDFilename())) returns a FileObject whose exists() is false — path typo, missing env variable substitution producing a bad path, or schema file deleted/moved.

Common situations: Schema lives only on a developer machine; relative path wrong because transformation run from a different working directory (e.g. in Carte/pan); ${INTERNAL_...} or custom env variable unset so the path becomes empty or wrong.

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/4d4aa1fa38b54c01. Report an issue: GitHub.

Appendix: source

Thrown at plugins/xml/core/src/main/java/org/pentaho/di/trans/steps/xsdvalidator/XsdValidator.java:118

        if ( meta.getResultfieldname() == null ) {
          // Result field is missing !
          logError( BaseMessages.getString( PKG, "XsdValidator.Log.ErrorResultFieldMissing" ) );
          throw new KettleStepException( BaseMessages.getString( PKG, "XsdValidator.Exception.ErrorResultFieldMissing" ) );
        }

        // Is XSD file is provided?
        if ( meta.getXSDSource().equals( meta.SPECIFY_FILENAME ) ) {
          if ( meta.getXSDFilename() == null ) {
            logError( BaseMessages.getString( PKG, "XsdValidator.Log.ErrorXSDFileMissing" ) );
            throw new KettleStepException( BaseMessages.getString( PKG, "XsdValidator.Exception.ErrorXSDFileMissing" ) );
          } else {
            // Is XSD file exists ?
            FileObject xsdfile = null;
            try {
              xsdfile = KettleVFS.getInstance( getTransMeta().getBowl() ).getFileObject( environmentSubstitute( meta.getXSDFilename() ), getTransMeta() );
              if ( !xsdfile.exists() ) {
                logError( BaseMessages.getString( PKG, "XsdValidator.Log.Error.XSDFileNotExists" ) );
                throw new KettleStepException( BaseMessages.getString( PKG, "XsdValidator.Exception.XSDFileNotExists" ) );
              }

            } catch ( Exception e ) {
              logError( BaseMessages.getString( PKG, "XsdValidator.Log.Error.GettingXSDFile" ) );
              throw new KettleStepException( BaseMessages.getString( PKG, "XsdValidator.Exception.GettingXSDFile" ) );
            } finally {
              try {
                if ( xsdfile != null ) {
                  xsdfile.close();
                }
              } catch ( IOException e ) {
                // Ignore errors
              }
            }
          }
        }

        // Is XSD field is provided?

View on GitHub (pinned to f3058517a1)