pentaho/pentaho-kettle · error · KettleException

Unable to load Kettle file repository meta object

Error message

Unable to load Kettle file repository meta object

What it means

KettleFileRepositoryMeta.loadXML() throws this KettleException when parsing the repository's XML metadata node fails while reading <base_directory>, <read_only>, or <hides_hidden_files> tags. This happens while loading repository connection metadata from a configuration file (e.g. repositories.xml or a shared settings file).

Solutions

  1. Inspect the cause stack trace to find the exact XML parse problem
  2. Validate/repair the repositories.xml (or relevant metadata file) containing the repository definition
  3. Re-create the file repository connection in Spoon to regenerate clean XML
  4. Verify the XML node uses the expected tag names (base_directory, read_only, hides_hidden_files)

Example fix

// before (broken repositories.xml fragment)
<repository><base_directory>/data/etw</read_only>Y</repository>
// after
<repository><description>File rep</description><base_directory>/data/etl</base_directory><read_only>Y</read_only><hides_hidden_files>N</hides_hidden_files></repository>
Defensive patterns

Strategy: try-catch

Validate before calling

// Validate repositories.xml before loading
Document doc = XMLHandler.loadXMLFile(new File(System.getProperty("user.home") + "/.kettle/repositories.xml"));
if (XMLHandler.getSubNode(doc.getDocumentElement(), "repositories") == null) {
  throw new IllegalStateException("Malformed repositories.xml");
}

Try / catch

try {
  repoMeta.loadXML(repnode, databases);
} catch (KettleException e) {
  log.error("Repository meta XML invalid; re-create the connection definition", e);
}

Prevention

When it happens

Trigger: XMLHandler.getTagValue() throws or the repnode is malformed/null while deserializing the repository metadata - corrupt configuration XML, wrong root node name, or unexpected XML structure.

Common situations: Manually edited or truncated .kettle/repositories.xml; upgrading Pentaho/Kettle versions where the metadata format changed; copying connection settings between machines with encoding damage.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/repository/filerep/KettleFileRepositoryMeta.java:110

    retval.append( "  " ).append( XMLHandler.openTag( XML_TAG ) );
    retval.append( super.getXML() );
    retval.append( "    " ).append( XMLHandler.addTagValue( "base_directory", baseDirectory ) );
    retval.append( "    " ).append( XMLHandler.addTagValue( "read_only", readOnly ) );
    retval.append( "    " ).append( XMLHandler.addTagValue( "hides_hidden_files", hidingHiddenFiles ) );
    retval.append( "  " ).append( XMLHandler.closeTag( XML_TAG ) );

    return retval.toString();
  }

  public void loadXML( Node repnode, List<DatabaseMeta> databases ) throws KettleException {
    super.loadXML( repnode, databases );
    try {
      baseDirectory = XMLHandler.getTagValue( repnode, "base_directory" );
      readOnly = "Y".equalsIgnoreCase( XMLHandler.getTagValue( repnode, "read_only" ) );
      hidingHiddenFiles = "Y".equalsIgnoreCase( XMLHandler.getTagValue( repnode, "hides_hidden_files" ) );
    } catch ( Exception e ) {
      throw new KettleException( "Unable to load Kettle file repository meta object", e );
    }
  }

  /**
   * @return the baseDirectory
   */
  public String getBaseDirectory() {
    return baseDirectory;
  }

  /**
   * @param baseDirectory
   *          the baseDirectory to set
   */
  public void setBaseDirectory( String baseDirectory ) {
    this.baseDirectory = baseDirectory;
  }

View on GitHub (pinned to f3058517a1)