pentaho/pentaho-kettle · error · KettleException

Unable to load cluster schema with id [idClusterSchema]

Error message

Unable to load cluster schema with id [idClusterSchema]

What it means

PurRepository.loadClusterSchema(idClusterSchema, versionId, ignoreErrors) fetches the file and version data for a cluster schema and assembles it via clusterTransformer; any exception (file not found, data unmarshal, transformer failure) is wrapped in this KettleException.

Solutions

1. Check e.getCause() for EntityNotFoundException vs data/transform failure.
2. Re-list cluster schemas (getClusterIDs/getClusterNames) and reload by fresh id.
3. If a versionId was passed, retry with null to load the latest version.
4. Verify the repository connection and that the object still exists in the Pentaho server.

Example fix

// before
ClusterSchema cs = repo.loadClusterSchema(staleId, someVersionId, false);
// after
try {
  ClusterSchema cs = repo.loadClusterSchema(staleId, null, false);
} catch (KettleException e) {
  log.warn("cluster schema " + staleId + " unavailable: " + e.getCause());
  cs = null; // fall back to re-listing shared objects
}

// verify the object still exists before loading
boolean present = Arrays.asList(repo.getClusterIDs(dirId)).contains(id);

boolean loadable(ObjectId id) { return id != null && id.getId() != null && !id.getId().isEmpty(); }

try { return repo.loadClusterSchema(id, null, false); } catch (KettleException e) { log.warn("cluster schema load failed: ", e.getCause()); return null; }

When it happens

Trigger: Calling loadClusterSchema with an ObjectId whose underlying repository file no longer exists (pur.getFileById returns null or throws), with an invalid versionId, or when the stored node data cannot be transformed.

Common situations: Cluster schema deleted by another user after the id was cached; shared-object id from a different repository; pur versioning service error; data format from an older Pentaho version that the transformer cannot assemble.

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 partition schema with id [partitionSchemaId]
• Unable to load slave server with id [idSlaveServer]
• TransMeta.Log.UnableToReadClustersFromRepository
• Unable to get all partition schema names
• Unable to get all slave server IDs

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

Appendix: source

Thrown at plugins/pur/core/src/main/java/org/pentaho/di/repository/pur/PurRepository.java:1875

  @Override
  public ClusterSchema loadClusterSchema( ObjectId idClusterSchema, List<SlaveServer> slaveServers, String versionId )
    throws KettleException {
    readWriteLock.readLock().lock();
    try {
      // We dont need to use slaveServer variable as the dataNoteToElement method finds the server from the repository
      NodeRepositoryFileData
        data =
        pur.getDataAtVersionForRead( idClusterSchema.getId(), versionId, NodeRepositoryFileData.class );
      RepositoryFile file = null;
      if ( versionId != null ) {
        file = pur.getFileAtVersion( idClusterSchema.getId(), versionId );
      } else {
        file = pur.getFileById( idClusterSchema.getId() );
      }

      return clusterTransformer.assemble( file, data, pur.getVersionSummary( idClusterSchema.getId(), versionId ) );
    } catch ( Exception e ) {
      throw new KettleException( "Unable to load cluster schema with id [" + idClusterSchema + "]", e );
    } finally {
      readWriteLock.readLock().unlock();
    }
  }

  @Override
  public Condition loadConditionFromStepAttribute( ObjectId idStep, String code ) throws KettleException {
    // implemented by RepositoryProxy
    throw new UnsupportedOperationException();
  }

  @Override
  public DatabaseMeta loadDatabaseMetaFromJobEntryAttribute( ObjectId idJobentry, String nameCode, int nr,
                                                             String idCode, List<DatabaseMeta> databases )
    throws KettleException {
    throw new UnsupportedOperationException();
  }

View on GitHub (pinned to f3058517a1)