23. Troubleshooting Errors

Use the troubleshooting information documented in this section to address errors that may appear while installing or using node-oracledb in Thin or Thick mode.

Questions about node-oracledb can be asked in GitHub Discussions or posted on Slack (link to join Slack).

23.1. Installation Errors

You may encounter issues while installing node-oracledb. Ensure that you have installed the node-oracledb prerequisites. Review the error messages closely.

  • If there is a network connection error, check if you need to use npm config set proxy, or set proxy environment variables such as http_proxy and/or https_proxy.

  • Use npm install --verbose oracledb. Review your output and logs.

  • If the installation problem still persists, then try to install node-oracledb in a different way. Google anything that looks like an error. Try some potential solutions.

  • Try running npm cache clean -f and deleting the node_modules/oracledb directory.

23.2. Error Messages

Some common DPI and NJS errors with node-oracledb Thin and Thick modes are detailed in this section. Each error includes information about the probable cause and the recommended action which may resolve the error.

23.2.1. DPI Error Messages

The error messages with prefix DPI are generated by the ODPI-C code which is used by the node-oracledb Thick mode.

23.2.1.1. DPI-1047

Message

DPI-1047: Cannot locate an Oracle Client library

Cause

Initializing node-oracledb Thick mode failed because the Oracle Client library could not be loaded.

Action

You can:

  • Review the features available in node-oracledb’s default Thin mode. If Thin mode suits your requirements, then remove calls in your application to oracledb.initOracleClient() since this loads the Oracle Client library to enable Thick mode.

  • Review any messages, the installation instructions, and see Initializing Node-oracledb.

  • On Windows and macOS, pass the lib_dir library directory parameter in your oracledb.initOracleClient() call. The parameter should be the location of your Oracle Client libraries. Do not pass this parameter on Linux.

  • Check if the Node.js process has permission to open the Oracle Client libraries. OS restrictions may prevent the opening of libraries installed in unsafe paths, such as from a user directory. On Linux you may need to install the Oracle Client libraries under a directory like /opt or /usr/local.

  • Check if Node.js and your Oracle Client libraries are both 64-bit or both 32-bit. The DPI-1047 message will tell you whether the 64-bit or 32-bit Oracle Client is needed for your Node.js. Run node -p 'process.arch' and compare with, for example, dumpbin /headers oci.dll (on Windows), file libclntsh.dylib (macOS) or file libclntsh.so.* (Linux).

  • Set the environment variable DPI_DEBUG_LEVEL to 64 and restart node-oracledb. The trace messages will show how and where node-oracledb is looking for the Oracle Client libraries.

    At a Windows command prompt, this could be done with:

    set DPI_DEBUG_LEVEL=64

    On Linux and macOS, you might use:

    export DPI_DEBUG_LEVEL=64

  • On Windows:

    • If node-oracledb is using libraries from a local database installation, ensure that this database is the currently configured database.

    • If you are not using passing a library directory parameter to oracledb.initOracleClient(), then restart your command prompt and use set PATH to check if the environment variable has the correct Oracle Client listed before any other Oracle directories.

    • Use the DIR command to verify that OCI.DLL exists in the directory passed to oracledb.initOracleClient() or set in PATH.

    • Check if the correct Windows Redistributables have been installed.

  • On Linux:

    • Check if the LD_LIBRARY_PATH environment variable contains the Oracle Client library directory. Some environments such as web servers reset environment variables.

    • If you are using Oracle Instant Client, a preferred alternative to LD_LIBRARY_PATH is to ensure that a file in the /etc/ld.so.conf.d directory contains the path to the Instant Client directory, and then run ldconfig.

23.2.1.2. DPI-1072

Message

DPI-1072: the Oracle Client library version is unsupported

Cause

The connection to Oracle Database failed because the Oracle Client library version used is not supported by node-oracledb Thick mode. The Thick mode needs Oracle Client libraries 11.2 or later. Note that version 19 is not supported on Windows 7.

Action

Review the installation requirements. You can either:

  • Follow the steps documented in DPI-1047 which may help.

  • Or maybe use node-oracledb Thin mode which can be done by removing calls to oracledb.initOracleClient() from your code.

23.2.2. NJS Error Messages

The node-oracledb Thin mode code and node-oracledb Thick mode code generates error messages with the prefix NJS.

23.2.2.1. NJS-116

Message

NJS-116: password verifier type 0x939 is not supported by node-oracledb in Thin mode.

Cause

Connecting to Oracle Database with node-oracledb Thin mode failed because your user account was only created with a 10G password verifier. The node-oracledb Thin mode supports password verifiers 11G and later. See Password Verifier Support.

Action

You can either:

  • Database administrators can verify if your username only uses the 10G password verifier with this query:

    SELECT USERNAME FROM DBA_USERS
WHERE ( PASSWORD_VERSIONS = '10G '
OR PASSWORD_VERSIONS = '10G HTTP ')
AND USERNAME <> 'ANONYMOUS';

    If your username uses the 10G password verifier, then you need to upgrade your password verifier in Oracle Database to 11G or later to use node-oracledb Thin mode. To upgrade your password verifier, see Finding and Resetting User Passwords That Use the 10G Password Verifier for the detailed steps.

  • Or enable Thick mode since node-oracledb Thick mode supports password verifiers 10G and later.