What causes "Step with id {0} could not be loaded from the repository!" in pentaho/pentaho-kettle?

Inspect the cause (getCause()) — it is a KettleDatabaseException with the real SQL/JDBC error; fix that root problem first.

pentaho/pentaho-kettle · error · KettleException

StepMeta.Exception.StepCouldNotBeLoaded

StepMeta.Exception.StepCouldNotBeLoaded

Error message

Step with id {0} could not be loaded from the repository!

What it means

In loadStepMeta(), if the initial step lookup succeeded but reading its metadata threw a KettleDatabaseException, the delegate wraps it in a KettleException with the message 'Step with id {0} could not be loaded from the repository!', preserving the database exception as the cause. It means the step row exists but its metadata could not be read from the database.

Solutions

Inspect the cause (getCause()) — it is a KettleDatabaseException with the real SQL/JDBC error; fix that root problem first.
Verify database connectivity and retry the load; transient network/timeout failures often succeed on retry.
Check grants on R_STEP / R_STEP_ATTRIBUTE for the repository user.
If the row is corrupted, delete and re-save the step/transformation from a working copy.

Example fix

// before
StepMeta step = repository.stepDelegate.loadStepMeta(stepId);
// after
try {
  StepMeta step = repository.stepDelegate.loadStepMeta(stepId);
} catch (KettleException e) {
  throw new KettleException("Loading step " + stepId + " failed: " + e.getCause().getMessage(), e);
}

Defensive patterns

Strategy: retry

Validate before calling

// verify connectivity first
if (!repository.isConnected()) repository.connect(repoMeta.getUser(), repoMeta.getPassword());

Try / catch

try {
  return repository.stepDelegate.loadStepMeta(stepId);
} catch (KettleException e) {
  Throwable cause = e.getCause();
  if (cause instanceof KettleDatabaseException) { /* inspect SQL error / retry */ }
  throw e;
}

Prevention

Keep repository connections alive with connection pooling/health checks
Check DB grants on R_STEP and attribute tables
Inspect getCause() for the true JDBC error before acting

When it happens

Trigger: repository.stepDelegate.loadStepMeta(stepId) is executing its loadStepAttributesMap / database reads when the underlying KettleDatabaseException occurs — e.g. connection dropped mid-load, corrupted R_STEP row, SQL error on R_STEP_ATTRIBUTE query, or lock/timeout on the repository tables.

Common situations: Repository DB connection timeout while loading large transformations; corrupted rows after an aborted migration; insufficient SELECT privileges on attribute tables; database failover during a load.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/repository/kdr/delegates/KettleDatabaseRepositoryStepDelegate.java:200

        String rowDistributionCode = repository.getStepAttributeString( stepId, 0, "row_distribution_code" );
        RowDistributionInterface rowDistribution =
          PluginRegistry.getInstance().loadClass(
            RowDistributionPluginType.class, rowDistributionCode, RowDistributionInterface.class );
        stepMeta.setRowDistribution( rowDistribution );

        // Load the attribute groups map
        //
        stepMeta.setAttributesMap( loadStepAttributesMap( stepId ) );

        // Done!
        //
        return stepMeta;
      } else {
        throw new KettleException( BaseMessages.getString(
          PKG, "StepMeta.Exception.StepInfoCouldNotBeFound", String.valueOf( stepId ) ) );
      }
    } catch ( KettleDatabaseException dbe ) {
      throw new KettleException( BaseMessages.getString( PKG, "StepMeta.Exception.StepCouldNotBeLoaded", String
        .valueOf( stepMeta.getObjectId() ) ), dbe );
    }
  }

  /**
   * Compatible loading of metadata for v4 style plugins using deprecated methods.
   *
   * @param stepMetaInterface
   * @param repository
   * @param objectId
   * @param databases
   * @throws KettleException
   */
  @SuppressWarnings( "deprecation" )
  private void readRepCompatibleStepMeta( StepMetaInterface stepMetaInterface,
    KettleDatabaseRepository repository, ObjectId objectId, List<DatabaseMeta> databases ) throws KettleException {
    stepMetaInterface.readRep( repository, objectId, databases, null );
  }

View on GitHub (pinned to f3058517a1)