Troubleshooting
This reference intends to guide you in addressing common errors in installing and running the Domino REST API service. Common errors and their corresponding resolutions are described below:
Address already in use error
You get this error when you run the sample script with the sample Notes database:
2021-01-28 15:39:07 ERROR Launch:707 - Management server failed to launch on 0.0.0.0:8889 2021-01-28 15:39:07 ERROR Launch:258 - Fatal java.net.BindException: Address already in use
Solution
Stop the process that's using the jar file. Use the Windows Task Manager, or on a Mac/Linux, do this:
ps -eaf | grep launch.class
kill -9 [pid number]
Authentication has gotten slower
Temporary files named keyutil_<somename>_
in Domino’s temp directory aren't removed after creation, causing slow authentication processing and eventual login timeouts.
Solution
Navigate to Domino’s temp folder, look for files with filenames starting with keyutil_
, and then remove these files.
Database is not fully initialized error
You get this error when you go to your Notes client and:
- Select File → Open → HCL Notes Application.
- Select
KeepConfig.nsf
file to open.
The following error is shown:
Solution
Delete the KeepConfig.nsf
from the Notes data directory and restart the sample script.
Tip
On Mac, the data directory path is /Users/[userid]/Library/Application Support/HCL Notes Data/
.
Domino Not Running (First-Time Setup)
If Domino isn't up and running, see Troubleshooting one-touch Domino Setup.
Domino REST API not responding
You get a timeout error when trying to access http://yourserver:8880
, wherein yourserver
is the DNS name of your Domino server.
Solution
You need to check if the REST API is loaded.
- In the Domino server console, type
show tasks
. - If there is no
restapi
entry in the list, load it usingload restapi
in the Domino console. - If it's listed, shut it down with
tell restapi quit
before tryingload restapi
. - Take note of any messages in case you need more support.
Domino REST API starts then stops working
This issue may be caused by conflicting libraries.
Solution:
-
Identify conflicting libraries.
Tip
Common conflicts involve the
Log4j
library.- Review the Domino REST API libraries in
{Domino REST API-install-directory}\libs
. - Compare these libraries with the libraries in
{DominoProgramDir}\jvm\lib\ext
. -
Identify any conflicting libraries between the two locations.
Note
The library names may not match exactly.
- Review the Domino REST API libraries in
-
Move the conflicting libraries from
{DominoProgramDir}\jvm\lib\ext
to{DominoProgramDir}\ndext
. - Restart the Domino REST API.
Expected result
The Domino REST API should start and function properly.
If Domino REST API does not start:
-
Examine
domino-keep.log
forFailed to load resource {pathToDominoData}\keepconfig.d\{somefile.json}
error, where{somefile.json}
is the file name of the configuration JSON file with an error.The possible causes of this error are:
- The configuration JSON file is an invalid JSON.
- The file contains unescaped or improperly escaped characters.
- The file is not UTF-8 encoded.
- The file does not use the US charset.
-
Correct the configuration JSON file using a local JSON validator, such as VS Code or Notepad++ with a JSON plugin.
Tip
Avoid using online validators as the file may contain customer data.
-
Restart the Domino REST API.
If Domino REST API still fails to start:
- Set
KeepAddinLogging=true
in thenotes.ini
file. - Restart the Domino REST API.
- Collect logs, such as
console.log
,domino-keep.log
, etc., and contact Support for further assistance.
Domino REST API stops working or crashes
If the Domino REST API stops working or crashes, it may be due to insufficient Java heap memory.
Solution:
-
Check for Java heap memory issues.
- Review the
domino-keep.log
anddomino-keep.*.log
files located in theIBM_TECHNICAL_SUPPORT
subdirectory of yourNotes/Domino
data directory. - Look for error messages indicating low memory or heap space issues, such as
java.lang.OutOfMemoryError: Java heap space
. - If there are errors, increase the Java heap size.
- Review the
-
Increase Java heap size.
- Determine the maximum physical memory you want to allocate for the Domino REST API to use.
-
Increase the heap memory allocated to Domino REST API by setting the value of the
KeepJavaHeapInMB
setting in thenotes.ini
file to the desired amount of memory in megabytes.For example, to allocate 32 GB, set:
KeepJavaHeapInMB=32000
-
Save the changes and restart the Domino REST API.
Getting a CORS error logging into Admin UI or when executing APIs
You get a CORS error when logging into the Admin UI or when executing APIs.
Note
Domino REST API v1.1.2 through v1.1.5 do not display a CORS error when logging into the Admin UI. Instead, after clicking the LOG IN button, the login fails without any error message. If you are experiencing this issue, the CORS error will still appear in the browser's Developer Tools.
To check if your error is related to CORS:
- Open the Admin UI login page in your browser.
- Open the Developer Tools by right-clicking anywhere on the webpage and choosing Inspect or Inspect Element from the context menu. Alternatively, you can use keyboard shortcuts: press F12 or Ctrl+Shift+I on Windows or Linux, or Cmd+Option+I on a Mac.
-
Select the Network tab and ensure that Console is visible at the bottom.
If Console is not visible, click the action menu represented by the three vertical dots in the top-right corner of the Developer Tools window and select Show console drawer.
-
Go to the Admin UI login page, and then log in to the Admin UI.
- Go to the Developer Tools and check the Console under the Network tab to see the CORS error. You may need to scroll to see all the error messages.
Solution:
You need to configure CORS. For more information, see Configure CORS for Admin UI, OAuth and your applications.
Getting an empty response when executing an API request method after a server upgrade
Check if the schema and the scope still exist. The schema is stored in the database the schema is for, while the scope is stored in KeepConfig.nsf
. There is a probability that the schema is missing. One possible reason for this is that the server upgrade replaced the design of the database, as opposed to just refreshing the design. Replacing the design removes all the design elements in the database, including the schema, and updates it with the latest design from a template. It can happen to both the system and non-system databases.
Solution:
- You can create a new schema and scope and repeat the API request method.
- You can then protect the individual design elements of your database, including the new schema you created. For more information, see the related topic in the Domino Designer documentation.
Unable to start the Domino REST API Domino task after updating configuration to use https
The KeepManagementURL
setting in your notes.ini
is the URL needed for the Domino REST API Domino task to talk to the Java side of Domino REST API. By default this is set to http
.
Solution
After updating the URL to https
, run load restapi
. For more information, see Domino REST API task.
User ID and password being requested repeatedly when using Notes for Domino REST API testing
Sometimes on the initial starting up of the Domino REST API or creation of KeepConfig and KeepAgents databases, or doing things like creating a folder in mail database, you are prompted for user ID and password repeatedly. This happens if the Don't prompt for a password checkbox under User Security isn't selected or if it gets reset based on the organization's policy.
Solution:
- Stop your Domino REST API debugging session.
- Go into Notes, and then select File → Security → User Security.
- Select the Don't prompt for a password from other Notes-based programs (reduces security) checkbox.
- Exit Notes and restart your Domino REST API debugging session.
This setting can get reset each time you start Notes depending upon your organization's Policy, in which case, you'll need to enable it again.