pentaho/pentaho-kettle · error · KettleException

Unable to load cluster schema from the file repository

Error message

Unable to load cluster schema from the file repository

What it means

loadClusterSchema(id, slaveServers, versionName) builds a ClusterSchema from the XML node loaded via loadNodeFromXML; any failure — the node cannot be loaded (missing file/parse error) or the ClusterSchema constructor rejects the XML — is wrapped in this fixed-message KettleException.

Solutions

1. Verify the cluster schema file for the ObjectId exists under the repository directory
2. Validate the XML contains a <cluster_schema> node and well-formed content
3. Recreate the cluster schema in Spoon and re-save it if the XML is corrupted
4. Check the chained cause to distinguish file loading from constructor parsing failures

Example fix

// before
ClusterSchema cs = repository.loadClusterSchema(id, slaveServers, null);
// after
ClusterSchema cs;
try {
  cs = repository.loadClusterSchema(id, slaveServers, null);
} catch (KettleException e) {
  cs = defaultClusterSchema(); // fallback or fail fast with context
}

// verify referenced id resolves before loading
if (id_cluster_schema == null) throw new KettleException("No cluster schema id set on transformation");

try {
  ClusterSchema cs = repository.loadClusterSchema(id, slaveServers, null);
} catch (KettleException e) {
  logger.error("Cluster schema load failed: " + e.getCause(), e);
  throw new KettleException("Recreate the cluster schema in the repository", e);
}

When it happens

Trigger: Calling loadClusterSchema with an ObjectId whose corresponding file is missing or unreadable, XML does not contain ClusterSchema.XML_TAG, or ClusterSchema's constructor throws while parsing fields (e.g. bad slave references).

Common situations: Cluster schema file deleted from the repository while a transformation still references it; hand-edited XML corrupted the node; version-control merge left an invalid cluster schema file in the repo.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• Unable to load database connection from the file repository
• Unable to load partition schema from the file repository
• AddSequenceMeta.Exception.ErrorLoadingStepInfo
• AggregateRowsMeta.Exception.UnableToLoadStepInfo
• AnalyticQueryMeta.Exception.UnableToLoadStepInfoFromXML

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/repository/filerep/KettleFileRepository.java:877

  }

  public ObjectId insertTransformationPartitionSchema( ObjectId id_transformation, ObjectId id_partition_schema ) throws KettleException {

    return null;
  }

  public ObjectId insertTransformationSlave( ObjectId id_transformation, ObjectId id_slave ) throws KettleException {

    return null;
  }

  @Override
  public ClusterSchema loadClusterSchema( ObjectId id_cluster_schema, List<SlaveServer> slaveServers,
    String versionName ) throws KettleException {
    try {
      return new ClusterSchema( loadNodeFromXML( id_cluster_schema, ClusterSchema.XML_TAG ), slaveServers );
    } catch ( Exception e ) {
      throw new KettleException( "Unable to load cluster schema from the file repository", e );
    }
  }

  public Condition loadCondition( ObjectId id_condition ) throws KettleException {

    return null;
  }

  @Override
  public Condition loadConditionFromStepAttribute( ObjectId id_step, String code ) throws KettleException {

    return null;
  }

  public Node loadNodeFromXML( ObjectId id, String tag ) throws KettleException {
    try {
      // The object ID is the base name of the file in the Base directory folder
      //

View on GitHub (pinned to f3058517a1)