Debugging Tips

Some hints and tips to help your problem determination

Common Error Messages

Error Message

Possible Reason

RunJava: Can't find class JAddIn

lotus/notes/addins/jaddin/Squirrel in the classpath. Class names are case-sensitive.

The RunJava task was unable to load the class. Make sure that it is written with exact upper and lower case characters and it can be found by the RunJava class loader

JAddin: Unable to load Java class Squirrel

The JAddin framework was unable to load Squirrel.jar. Make sure that it is written with exact upper and lower case characters.

RunJava: Can't find stopAddin method for class Squirrel.

The Squirrel class must be loaded thru the JAddin framework and not directly from RunJava. Use the command Load RunJava JAddin Squirrel to start Squirrel.

RunJava JVM: java.lang.NoClassDefFoundError: Squirrel (wrong name: sqirrel)

The user class name in the command and the internal name do not match. Most likely you have not typed the name with correct upper and lower case characters.

Out of memory

All Java add-ins execute in a single Java Virtual Machine (JVM) in RunJava. The Domino Notes.Ini parameter 'JavaMaxHeapSize=xxxxMB' may be used to increase the heap space.

HCL Domino Statistics

During execution, the Squirrel add-in maintains statistics and status information. They can be displayed with the Show Stat Squirrel command:

> Show Stat Squirrel
Squirrel.Config.IntervalMin = 3
Squirrel.Config.Subscriptions.Limit = 5
Squirrel.Config.Subscriptions.Used = 2
Squirrel.Domino.Platform = 6.2 (Windows 8)
Squirrel.Domino.Version = Release 11.0.1FP2|October 20, 2020 (Windows/64)
Squirrel.JAddin.StartedTime = 2021-01-25T15:39:48Z
Squirrel.JAddin.VersionDate = 2021-01-25
Squirrel.JAddin.VersionNumber = 2.1.2
Squirrel.JVM.GCCount = 0
Squirrel.JVM.HeapLimitKB = 262'144
Squirrel.JVM.HeapUsedKB = 19'482
Squirrel.JVM.Version = 1.8.0_265 (Eclipse OpenJ9)
Squirrel.Messages.IMAP.Processed = 32
Squirrel.Messages.LastConnectTime = 2021-01-25T15:39:49Z
Squirrel.Messages.POP3.Processed = 2
Squirrel.VersionDate = 2021-01-01
Squirrel.VersionNumber = 1.4.3

Connection Problems

Basic Connection Test

If Squirrel is unable to connect to the Internet mail server, check if a direct connection from the HCL Domino server to the specified Internet mail server is possible. This can be done with Telnet or NetCat.

> nc -v imap.gmail.com 993
Connection to imap.gmail.com port 993 [tcp/imaps] succeeded!

TLS Connection Test

To check which TLS certificate the Internet mail server is using, you may issue the openssl command:

> openssl s_client -connect imap.gmail.com:993
CONNECTED(00000006)
depth=2 OU = GlobalSign Root CA - R2, O = GlobalSign, CN = GlobalSign
verify return:1
depth=1 C = US, O = Google Trust Services, CN = Google Internet Authority G3
verify return:1
depth=0 C = US, ST = California, L = Mountain View, O = Google LLC, CN = imap.gmail.com
verify return:1
---
Certificate chain
0 s:/C=US/ST=California/L=Mountain View/O=Google LLC/CN=imap.gmail.com
i:/C=US/O=Google Trust Services/CN=Google Internet Authority G3
1 s:/C=US/O=Google Trust Services/CN=Google Internet Authority G3
i:/OU=GlobalSign Root CA - R2/O=GlobalSign/CN=GlobalSign
...

Secure connections are supported by using the TLS variant of the IMAP and POP3 protocol (IMAPS and POP3S). The JVM of the HCL Domino server is using the keystore file 'domino/jvm/lib/security/cacert' to validate the TLS certificates. If the root certificate is not found in the keystore file, you need to add the root (and intermediate) certificates from the connecting mail server into this 'cacert' file.

Add Certificate to Keystore File

To import the missing root and/or intermediate certificates:

HCL Domino 11+

  1. Open command prompt window with administrator priviledge on the HCL Domino server

  2. cd domino\jvm\bin to change to the directory

  3. Add the certificate to the 'cacert' file, e.g. keytool -import -trustcacerts -keystore jvm/lib/security/cacerts -storepass changeit -alias "New Root CA" -import -file NewRootCA.pem

  4. Restart the HCL Domino server

HCL Domino 9 and 10:

  1. Open command prompt window with administrator privilege on the HCL Domino server

  2. cd domino\jvm\bin to change to the directory

  3. ikeyman to start the IBM Key Management utility

  4. Click 'Key Database File' and then 'Open'. Select the file 'cacerts' in the directory 'domino\jvm\lib\security'. You need to have 'All files' selected to see it. The password to open the file is 'changeit'.

  5. Change to 'Signer Certificates'

  6. Click 'Add' and select the root (or intermediate) certificate you need to import. Click 'OK' and enter any descriptive text for this certificate.

  7. Restart the HCL Domino server.

Debugging

For a detailed problem determination, you may use the built-in debugging features.

Enable/Disable Debug

Domino Console Command

Description

Load RunJava JAddin Squirrel Debug!

Start Squirrel add-in in debug mode

Tell Squirrel Debug!

Start the debug mode while the add-in is running

Tell Squirrel NoDebug!

Stop the debug mode while the add-in is running

While active debugging adds a significant amount of data to the console log and to the log.nsf database, it can be helpful in finding the root of a problem.

Debugging Squirrel

When activated, the HCL Domino console shows debugging information from the Squirrel add-in and the underlying JAddin framework. The output includes the name of the Java method with the source line number issuing the message.

> Load RunJava JAddin Squirrel Debug!
05.02.2019 07:44:15 JVM: Java Virtual Machine initialized.
05.02.2019 07:44:15 RunJava: Started JAddin Java task.
05.02.2019 07:44:15 JAddin: Debug logging enabled - Enter 'Tell Squirrel NoDebug!' to disable
05.02.2019 07:44:15 DEBUG: JAddin.runNotes(144) JAddin framework version 2.1.0
05.02.2019 07:44:15 DEBUG: JAddin.runNotes(145) Squirrel will be called with parameters null
05.02.2019 07:44:15 DEBUG: JAddin.runNotes(148) Creating the Domino message queue
05.02.2019 07:44:15 DEBUG: JAddin.runNotes(166) Opening the Domino message queue
05.02.2019 07:44:15 DEBUG: JAddin.runNotes(184) Loading the user Java class Squirrel
05.02.2019 07:44:15 DEBUG: JAddin.runNotes(196) User Java class Squirrel successfully loaded
05.02.2019 07:44:15 DEBUG: JAddin.runNotes(208) => Squirrel.addinInitialize()
05.02.2019 07:44:15 DEBUG: Squirrel.addinInitialize(80) -- addinInitialize()
05.02.2019 07:44:15 DEBUG: Squirrel.addinInitialize(94) Creating the Domino session
05.02.2019 07:44:15 DEBUG: JAddin.runNotes(210) <= Squirrel.addinInitialize()
05.02.2019 07:44:15 DEBUG: JAddin.runNotes(221) => Squirrel.start()
05.02.2019 07:44:15 DEBUG: JAddin.runNotes(223) <= Squirrel.start()
05.02.2019 07:44:15 DEBUG: Squirrel.runNotes(117) -- runNotes()
05.02.2019 07:44:15 DEBUG: Squirrel.runNotes(130) => Squirrel.addinStart()
05.02.2019 07:44:15 Squirrel: The Internet Mail Collector for HCL Domino - Version 1.0.0 2019-02-01
05.02.2019 07:44:15 Squirrel: Copyright iota systems GmbH 2019 / ABdata, Andy Brunner 2019. All Rights Reserved.
05.02.2019 07:44:15 DEBUG: Squirrel.addinStart(182) Configuration database Squirrel.nsf successfully opened
05.02.2019 07:44:15 DEBUG: Squirrel.readConfiguration(384) Reading configuration document
05.02.2019 07:44:15 DEBUG: Squirrel.checkServerLicense(461) License key: null
05.02.2019 07:44:15 Squirrel: No valid license key found - Running in test mode (1 active subscription, 3 messages)
05.02.2019 07:44:15 DEBUG: Squirrel.readConfiguration(417) Configuration document successfully processed
05.02.2019 07:44:15 DEBUG: Squirrel.newVersionCheck(311) -- newVersionCheck()
05.02.2019 07:44:16 DEBUG: Squirrel.newVersionCheck(321) Available version on website: 1.0.0
05.02.2019 07:44:16 DEBUG: Squirrel.readSubscriptions(431) Read all subscription documents
05.02.2019 07:44:16 DEBUG: Squirrel.dbGetAllDocuments(633) View Squirrel.nsf/($Accounts) entries: 1
05.02.2019 07:44:16 DEBUG: Squirrel.addinStart(196) Subscription documents: 1
05.02.2019 07:44:16 DEBUG: Squirrel.addinStart(239) Subscription [email protected]: POP3S pop.acme.com:995 => John Smith/ACME
05.02.2019 07:44:16 DEBUG: Squirrel.addinStart(242) Subscription [email protected]: Keep mail on server: 1
05.02.2019 07:44:16 DEBUG: Squirrel.readInbox(607) Subscription [email protected]: Last POP3 Time stamp: 2019-02-03T11:56:46Z
05.02.2019 07:44:17 DEBUG: Squirrel.readInbox(623) Subscription [email protected]: Login successful
05.02.2019 07:44:17 DEBUG: Squirrel.readInbox(675) Subscription [email protected]: Messages in inbox: 4
05.02.2019 07:44:17 DEBUG: Squirrel.readInbox(706) Subscription [email protected]: Unread POP3 messages: 4
05.02.2019 07:44:17 DEBUG: Squirrel.addinStart(256) Subscription [email protected]: Processing next message
05.02.2019 07:44:17 DEBUG: Squirrel.addinStart(270) Subscription [email protected]: Message object: [email protected]
...

Debugging Eclipse Jakarta Mail

In addition to the debugging information sent to the HCL Domino console, the Eclipse Jakarta Mail is instructed to create debugging output. Due to the amount of information, the data is written to a separate file with the name 'Squirrel-Debug-YYYY-MM-YY.log' in the HCL Domino data directory.

Squirrel for Domino - Version 1.5.0 - Jakarta mail debug log started 2021-04-10 14:03:49
Mail property mail.imaps.port: 993
Mail property mail.store.protocol: imaps
Mail property mail.imaps.partialfetch: false
Mail property mail.mime.decodetext.strict: false
Mail property mail.imaps.peek: true
Mail property mail.mime.charset: UTF-8
DEBUG: setDebug: Jakarta Mail version 1.6.6-SNAPSHOT
DEBUG: getProvider() returning javax.mail.Provider[STORE,imaps,com.sun.mail.imap.IMAPSSLStore,Oracle]
DEBUG IMAPS: mail.imap.partialfetch: false
DEBUG IMAPS: mail.imap.ignorebodystructuresize: false
DEBUG IMAPS: mail.imap.statuscachetimeout: 1000
DEBUG IMAPS: mail.imap.appendbuffersize: -1
DEBUG IMAPS: mail.imap.minidletime: 10
DEBUG IMAPS: peek
DEBUG IMAPS: closeFoldersOnStoreFailure
DEBUG IMAPS: trying to connect to host "imap.servicehoster.ch", port 993, isSSL true
* OK [CAPABILITY IMAP4rev1 SASL-IR LOGIN-REFERRALS ID ENABLE IDLE LITERAL+ AUTH=PLAIN AUTH=LOGIN] Dovecot ready.
DEBUG IMAPS: AUTH: PLAIN
DEBUG IMAPS: AUTH: LOGIN
DEBUG IMAPS: protocolConnect login, host=imap.servicehoster.ch, [email protected], password=<non-null>
DEBUG IMAPS: AUTHENTICATE PLAIN command trace suppressed
DEBUG IMAPS: AUTHENTICATE PLAIN command result: A0 OK [CAPABILITY IMAP4rev1 SASL-IR LOGIN-REFERRALS ID ENABLE IDLE SORT SORT=DISPLAY THREAD=REFERENCES THREAD=REFS THREAD=ORDEREDSUBJECT MULTIAPPEND URL-PARTIAL CATENATE UNSELECT CHILDREN NAMESPACE UIDPLUS LIST-EXTENDED I18NLEVEL=1 CONDSTORE QRESYNC ESEARCH ESORT SEARCHRES WITHIN CONTEXT=SEARCH LIST-STATUS BINARY MOVE SNIPPET=FUZZY PREVIEW=FUZZY LITERAL+ NOTIFY SPECIAL-USE QUOTA] Logged in
DEBUG IMAPS: connection available -- size: 1
A1 SELECT INBOX
* FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
* OK [PERMANENTFLAGS (\Answered \Flagged \Deleted \Seen \Draft \*)] Flags permitted.
* 0 EXISTS
* 0 RECENT
* OK [UIDVALIDITY 1614859984] UIDs valid
* OK [UIDNEXT 2] Predicted next UID
A1 OK [READ-WRITE] Select completed (0.001 + 0.000 + 0.001 secs).
A2 SEARCH UNSEEN ALL
* SEARCH
A2 OK Search completed (0.001 + 0.000 secs).
A3 CLOSE

Don't forget to manually delete these debug files after use.