Skip to content

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:

  1. Select File → Open → HCL Notes Application.
  2. Select KeepConfig.nsf file to open.

The following error is shown:

KeepConfigDBError

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.

  1. In the Domino server console, type show tasks.
  2. If there is no restapi entry in the list, load it using load restapi in the Domino console.
  3. If it's listed, shut it down with tell restapi quit before trying load restapi.
  4. 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:

  1. Identify conflicting libraries.

    Tip

    Common conflicts involve the Log4j library.

    1. Review the Domino REST API libraries in {Domino REST API-install-directory}\libs.
    2. Compare these libraries with the libraries in {DominoProgramDir}\jvm\lib\ext.

    3. Identify any conflicting libraries between the two locations.

      Note

      The library names may not match exactly.

  2. Move the conflicting libraries from {DominoProgramDir}\jvm\lib\ext to {DominoProgramDir}\ndext.

  3. Restart the Domino REST API.

Expected result

The Domino REST API should start and function properly.

If Domino REST API does not start:

  1. Examine domino-keep.log for Failed 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.

  2. 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.

  3. Restart the Domino REST API.

If Domino REST API still fails to start:

  1. Set KeepAddinLogging=true in the notes.ini file.
  2. Restart the Domino REST API.
  3. 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:

  1. Check for Java heap memory issues.

    1. Review the domino-keep.log and domino-keep.*.log files located in the IBM_TECHNICAL_SUPPORT subdirectory of your Notes/Domino data directory.
    2. Look for error messages indicating low memory or heap space issues, such as java.lang.OutOfMemoryError: Java heap space.
    3. If there are errors, increase the Java heap size.

  2. Increase Java heap size.

    1. Determine the maximum physical memory you want to allocate for the Domino REST API to use.

    2. Increase the heap memory allocated to Domino REST API by setting the value of the KeepJavaHeapInMB setting in the notes.ini file to the desired amount of memory in megabytes.

      For example, to allocate 32 GB, set:

      KeepJavaHeapInMB=32000

  3. 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:

  1. Open the Admin UI login page in your browser.
  2. 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.

  3. 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.

  4. Go to the Admin UI login page, and then log in to the Admin UI.

  5. 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:

  1. Stop your Domino REST API debugging session.
  2. Go into Notes, and then select File → Security → User Security.
  3. Select the Don't prompt for a password from other Notes-based programs (reduces security) checkbox.
  4. 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.