What causes "JobGetMailsFromPOP.Error.NewConnection" in pentaho/pentaho-kettle?

Inspect the cause stack trace (this exception wraps the real cause) to identify whether it is DNS, connect, SSL, or authentication failure.

pentaho/pentaho-kettle · error · KettleException

JobGetMailsFromPOP.Error.NewConnection

Error message

JobGetMailsFromPOP.Error.NewConnection

What it means

MailConnection.connect() wraps the entire connection setup (session creation, proxy/SSL configuration, store configuration) and on any Exception throws this KettleException, message 'Error connecting to mail server' style with the server name appended as a parameter, and the underlying exception as cause. It signals that a mail connection to the configured POP3/IMAP server could not be established.

Solutions

Inspect the cause stack trace (this exception wraps the real cause) to identify whether it is DNS, connect, SSL, or authentication failure.
Verify server name, port, protocol (POP3 vs IMAP), and SSL/STARTTLS settings in the job entry against the mail provider's documented values.
Test reachability and credentials with a standalone client (openssl s_client -connect host:port, or a mail client) from the same machine as the job.
Confirm the mailbox allows the protocol and the credentials/app-password/OAuth token are valid and not expired.

Example fix

// before: SSL on port 143
new MailConnection(..., PROTOCOL_IMAP, "mail.example.com", 143, user, pass, useSSL=true, ...)
// after: correct TLS setup
new MailConnection(..., PROTOCOL_IMAP, "mail.example.com", 993, user, pass, useSSL=true, ...)

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-flight reachability check
try (Socket s = new Socket()) {
  s.connect(new InetSocketAddress(server, port), 5000);
} catch (IOException e) {
  throw new IllegalStateException("Mail server unreachable: " + server + ":" + port, e);
}

Try / catch

try {
  mailConn.connect();
} catch (KettleException e) {
  logError("Could not connect to mail server " + server + ": " + e.getCause());
  // inspect e.getCause() for UnknownHostException / SSLException / AuthenticationFailedException
}

Prevention

Verify protocol/port/SSL combination against the provider docs (993/SSL or 143/STARTTLS, 995/SSL or 110/STARTTLS).
Enable the required protocol (IMAP/POP) in the mailbox provider settings.
Use app passwords or OAuth tokens where providers disallow plain passwords.
Test connectivity with openssl s_client from the machine running kitchen before scheduling.

When it happens

Trigger: new MailConnection(...).connect() -> connect()/configureMailStore() throws for any reason: unknown host, refused port, SSL handshake failure, failed login/authentication, wrong protocol/port combination, proxy misconfiguration.

Common situations: Wrong server hostname or port; POP3/IMAP disabled on the mailbox (e.g. Gmail requires enabling IMAP); SSL/TLS mismatch (SSL toggled when the server expects STARTTLS on 143); bad username/password or OAuth password not prefixed correctly; firewall/DNS issues in the runtime environment.

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

Appendix: source

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

    this.nrDeletedMessages = 0;
    this.nrMovedMessages = 0;
    this.nrSavedAttachedFiles = 0;
    this.messagenr = -1;
    this.useproxy = useproxy;
    this.proxyusername = proxyusername;

    try {
      configureProxySettings();
      configurePOP3Settings();
      configureOAuthSettings();
      configureTimeoutSettings();
      configureMailStore();

      if ( log.isDetailed() ) {
        log.logDetailed( BaseMessages.getString( PKG, "JobGetMailsFromPOP.NewConnectionDefined" ) );
      }
    } catch ( Exception e ) {
      throw new KettleException( BaseMessages.getString( PKG, "JobGetMailsFromPOP.Error.NewConnection", Const.NVL(
        this.server, "" ) ), e );
    }
  }

  private void configureProxySettings() {
    if ( this.useproxy ) {
      // Need here to pass a proxy
      // use SASL authentication
      this.prop.put( "mail.imap.sasl.enable", "true" );
      this.prop.put( "mail.imap.sasl.authorizationid", this.proxyusername );
    }
  }

  private void configurePOP3Settings() {
    if ( this.protocol == MailConnectionMeta.PROTOCOL_POP3 ) {
      this.prop.setProperty( "mail.pop3s.rsetbeforequit", "true" );
      this.prop.setProperty( "mail.pop3.rsetbeforequit", "true" );
    }

View on GitHub (pinned to f3058517a1)