pentaho/pentaho-kettle · error · KettleException

JobGetMailsFromPOP.Error.Connecting

Error message

JobGetMailsFromPOP.Error.Connecting

What it means

MailConnection.connect() wraps any exception from establishing the JavaMail Session/Store connection (store.connect) into a KettleException with the JobGetMailsFromPOP.Error.Connecting message, which includes server, username and port. It means the email entry could not log in to the mail server at all — DNS, network, TLS, credentials or protocol problems all land here with the original cause attached.

Solutions

  1. Verify server hostname, port and use-SSL/use-XOAUTH2 settings in the 'Get mails (POP3/IMAP)' job entry dialog; test with 'telnet host port' or openssl s_client.
  2. Re-enter username/password — POP/IMAP authentication failures surface here.
  3. Check network/firewall/DNS from the Pentaho host; the cause chained in the stack trace names the underlying IOException.
  4. For self-signed servers, import the certificate into the JVM truststore or set MailConnectionMeta SSL/trust properties.

Example fix

// before: wrong port with SSL
server="mail.example.com", port=110, useSSL=true
// after
server="mail.example.com", port=995, useSSL=true
Defensive patterns

Strategy: try-catch

Validate before calling

// before running the job entry
InetAddress addr = InetAddress.getByName(server); // resolves DNS
try (Socket s = new Socket()) { s.connect(new InetSocketAddress(addr, port), 5000); } // port reachable

Try / catch

try {
  mailConnection.connect();
} catch (KettleException e) {
  // e.getCause() holds the javax.mail.MessagingException/IOException
  logError("Cannot reach " + server + ":" + port + " — " + e.getCause().getMessage());
  throw e;
}

Prevention

When it happens

Trigger: store.connect() throws: unknown host, connection refused/timeout, STARTSSL/SSL handshake failure, or authentication rejected for the configured server/username/port in connect().

Common situations: Wrong POP3/IMAP host or port (995/993 vs 110/143), password changed or account locked, firewall blocks outbound mail ports, mail server requires SSL but 'use SSL' was not checked, self-signed certificates rejected.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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

Appendix: source

Thrown at plugins/email-messages/impl/src/main/java/org/pentaho/di/job/entries/getpop/MailConnection.java:378

  public void connect() throws KettleException {
    if ( log.isDetailed() ) {
      log.logDetailed( BaseMessages.getString(
        PKG, "JobGetMailsFromPOP.Connecting", this.server, this.username, "" + this.port ) );
    }
    try {
      if ( this.protocol == MailConnectionMeta.PROTOCOL_MBOX ) {
        connectMbox();
        return;
      }

      connectToMailServer();

      if ( log.isDetailed() ) {
        log.logDetailed( BaseMessages.getString(
          PKG, "JobGetMailsFromPOP.Connected", this.server, this.username, "" + this.port ) );
      }
    } catch ( Exception e ) {
      throw new KettleException(
        BaseMessages.getString( PKG, "JobGetMailsFromPOP.Error.Connecting", this.server, this.username, Const
          .NVL( "" + this.port, "" ) ), e );
    }
  }

  private void connectMbox() throws KettleException {
    this.mboxMessages = loadMboxMessages();
    this.mboxConnected = true;
    this.messages = this.mboxMessages;
  }

  private void connectToMailServer() throws MessagingException {
    if ( shouldUseSSLConnection() ) {
      this.store.connect();
    } else {
      connectWithPassword();
    }
  }

View on GitHub (pinned to f3058517a1)