pentaho/pentaho-kettle · error · KettleException

Unable to load step type 'mail' from the repository with…

Error message

Unable to load step type 'mail' from the repository with id_step=

What it means

MailMeta's repository-load constructor catches a KettleDatabaseException while reading mail step attributes and rethrows it as a KettleException. The step metadata could not be read from the repository database for the given id_step.

Solutions

Check the chained KettleDatabaseException cause for the root SQL error (connectivity, permissions, missing table).
Verify repository database connectivity and credentials, then retry loading the transformation.
If repository records are corrupted, re-save the transformation from a file copy or re-import it into the repository.
Repair orphaned r_step_attribute rows for the reported id_step if a partial delete/insert left the step inconsistent.

Defensive patterns

Strategy: try-catch

Validate before calling

// Before loading, verify the repository connection is healthy
if (rep == null || !rep.isConnected()) {
  throw new KettleException("Repository not connected; cannot load mail step.");
}

Try / catch

try { loadTransFromRepo(id); } catch (KettleException e) {
  logError("Repository load of mail step failed for id_step: " + e.getMessage(), e);
  // fall back to file-based copy if available
}

Prevention

Keep repository schema upgraded in lockstep with the Pentaho version.
Monitor repository DB connectivity and connection-pool health.
Keep file-based exports (.ktr) as recoverable copies of repository content.

When it happens

Trigger: loadRep from a repository database where the underlying KettleDatabaseException occurs: missing ktr rows, corrupted r_step_attribute records, repository connection dropped mid-read.

Common situations: Repository DB migrated/upgraded between Pentaho versions leaving orphaned attributes; database connection pool exhausted; transformation referenced from a different repository id space.

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/168121f4c7e64831. Report an issue: GitHub.

Appendix: source

Thrown at plugins/mail/impl/src/main/java/org/pentaho/di/trans/steps/mail/MailMeta.java:1029

      this.usePriority = rep.getStepAttributeBoolean( id_step, TAG_USE_PRIORITY );
      this.secureConnectionType = rep.getStepAttributeString( id_step, TAG_SECURE_CONNECTION_TYPE );

      this.zipFiles = rep.getStepAttributeBoolean( id_step, TAG_ZIP_FILES );
      this.zipFilename = rep.getStepAttributeString( id_step, TAG_ZIP_NAME );
      this.zipLimitSize = rep.getStepAttributeString( id_step, TAG_ZIP_LIMIT_SIZE );

      // How many arguments?
      int imagesNr = rep.countNrStepAttributes( id_step, TAG_EMBEDDED_IMAGE );

      allocate( imagesNr );

      // Read them all...
      for ( int a = 0; a < imagesNr; a++ ) {
        embeddedImages[a] = rep.getStepAttributeString( id_step, a, TAG_EMBEDDED_IMAGE );
        contentIds[a] = rep.getStepAttributeString( id_step, a, "contentid" );
      }
    } catch ( KettleDatabaseException dbe ) {
      throw new KettleException(
        "Unable to load step type 'mail' from the repository with id_step=" + id_step, dbe );
    }
  }

  @Override
  public void saveRep( Repository rep, IMetaStore metaStore, ObjectId id_transformation, ObjectId id_step ) throws KettleException {
    try {
      rep.saveStepAttribute( id_transformation, id_step, TAG_SERVER, this.server );
      rep.saveStepAttribute( id_transformation, id_step, TAG_PORT, this.port );
      rep.saveStepAttribute( id_transformation, id_step, TAG_DESTINATION, this.destination );
      rep.saveStepAttribute( id_transformation, id_step, TAG_DESTINATION_CC, this.destinationCc );
      rep.saveStepAttribute( id_transformation, id_step, TAG_DESTINATION_BCC, this.destinationBCc );
      rep.saveStepAttribute( id_transformation, id_step, TAG_REPLYTO_ADDRESSES, this.replyToAddresses );
      rep.saveStepAttribute( id_transformation, id_step, TAG_REPLYTO, this.replyAddress );
      rep.saveStepAttribute( id_transformation, id_step, TAG_REPLYTO_NAME, this.replyName );

      rep.saveStepAttribute( id_transformation, id_step, TAG_SUBJECT, this.subject );
      rep.saveStepAttribute( id_transformation, id_step, TAG_INCLUDE_DATE, this.includeDate );

View on GitHub (pinned to f3058517a1)