{"record":{"id":"c24466908c02e0fa","repo":"pentaho/pentaho-kettle","slug":"jobgetmailsfrompop-error-newconnection","errorCode":null,"errorMessage":"JobGetMailsFromPOP.Error.NewConnection","messagePattern":"JobGetMailsFromPOP\\.Error\\.NewConnection","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"plugins/email-messages/impl/src/main/java/org/pentaho/di/job/entries/getpop/MailConnection.java","lineNumber":233,"sourceCode":"    this.nrDeletedMessages = 0;\n    this.nrMovedMessages = 0;\n    this.nrSavedAttachedFiles = 0;\n    this.messagenr = -1;\n    this.useproxy = useproxy;\n    this.proxyusername = proxyusername;\n\n    try {\n      configureProxySettings();\n      configurePOP3Settings();\n      configureOAuthSettings();\n      configureTimeoutSettings();\n      configureMailStore();\n\n      if ( log.isDetailed() ) {\n        log.logDetailed( BaseMessages.getString( PKG, \"JobGetMailsFromPOP.NewConnectionDefined\" ) );\n      }\n    } catch ( Exception e ) {\n      throw new KettleException( BaseMessages.getString( PKG, \"JobGetMailsFromPOP.Error.NewConnection\", Const.NVL(\n        this.server, \"\" ) ), e );\n    }\n  }\n\n  private void configureProxySettings() {\n    if ( this.useproxy ) {\n      // Need here to pass a proxy\n      // use SASL authentication\n      this.prop.put( \"mail.imap.sasl.enable\", \"true\" );\n      this.prop.put( \"mail.imap.sasl.authorizationid\", this.proxyusername );\n    }\n  }\n\n  private void configurePOP3Settings() {\n    if ( this.protocol == MailConnectionMeta.PROTOCOL_POP3 ) {\n      this.prop.setProperty( \"mail.pop3s.rsetbeforequit\", \"true\" );\n      this.prop.setProperty( \"mail.pop3.rsetbeforequit\", \"true\" );\n    }","sourceCodeStart":215,"sourceCodeEnd":251,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/email-messages/impl/src/main/java/org/pentaho/di/job/entries/getpop/MailConnection.java#L215-L251","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: SSL on port 143\nnew MailConnection(..., PROTOCOL_IMAP, \"mail.example.com\", 143, user, pass, useSSL=true, ...)\n// after: correct TLS setup\nnew MailConnection(..., PROTOCOL_IMAP, \"mail.example.com\", 993, user, pass, useSSL=true, ...)","handlingStrategy":"try-catch","validationCode":"// pre-flight reachability check\ntry (Socket s = new Socket()) {\n  s.connect(new InetSocketAddress(server, port), 5000);\n} catch (IOException e) {\n  throw new IllegalStateException(\"Mail server unreachable: \" + server + \":\" + port, e);\n}","typeGuard":null,"tryCatchPattern":"try {\n  mailConn.connect();\n} catch (KettleException e) {\n  logError(\"Could not connect to mail server \" + server + \": \" + e.getCause());\n  // inspect e.getCause() for UnknownHostException / SSLException / AuthenticationFailedException\n}","preventionTips":["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."],"tags":["email","imap","pop3","connection","ssl","network"],"backgroundTag":"connection-refused","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}