Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

node-oracledb DPI-1047 and libclntsh.so cannot open shared object file

ErrorDPI-1047: Cannot locate an Oracle Client library

Short answer

DPI-1047 means Thick mode was switched on but the Oracle Client library could not be loaded. Since node-oracledb 6 you often do not need it: Thin mode connects without Instant Client. If you need Thick mode, put the Instant Client folder in the system library path with ldconfig and install libaio.

  • Applies to node-oracledb 6, Node.js 22, Oracle Instant Client 23, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Turn on the library's own trace. It prints every place node-oracledb searched, which shows at once whether the folder is on the search path.

    DPI_DEBUG_LEVEL=64 node app.js
  2. 2Match what you see, then jump to its fix

    1. 1The error appears on the call to initOracleClient(), and Instant Client was never installedinitOracleClient() is called but you do not need Thick modeFix
    2. 2DPI_DEBUG_LEVEL=64 shows the search ending without finding libclntsh.soThe Instant Client folder is not in the system library pathFix
    3. 3The library is on the path, but loading still fails and libaio.so.1 is not foundlibaio is missingFix
    4. 4The error says 64-bit library, or the file command shows 32-bit librariesNode.js and the client library differ in bitnessFix
    5. 5An old client such as the 12.1 library in the file name, or error DPI-1072The Oracle Client library is too old for Thick modeFix

What does the error look like?

  • DPI-1047: Cannot locate an Oracle Client library
  • DPI-1047: Cannot locate a 64-bit Oracle Client library

Cause 1 of 5

initOracleClient() is called but you do not need Thick mode

1Check

By default node-oracledb runs in Thin mode, which connects directly to Oracle Database and needs no Oracle Client libraries. Search the code for the call.

grep -rn "initOracleClient" src/

2Fix

Remove the initOracleClient() call to stay in Thin mode, unless you need a feature that only Thick mode has.

// remove this line
// oracledb.initOracleClient();

3Verify

The app connects without any Instant Client installed.

node app.js

Confirmed by node-oracledb.readthedocs.io

Did this fix it?

Cause 2 of 5

The Instant Client folder is not in the system library path

1Check

On Linux the libraries are found through the operating system's search path, which must be set before Node.js starts. The docs say never to pass libDir on Linux. Daemons and web servers often reset environment variables, so ldconfig is preferred over LD_LIBRARY_PATH.

ls /opt/oracle/instantclient_23_26/libclntsh.so*
ldconfig -p | grep clntsh

2Fix

Register the folder with ldconfig and call initOracleClient() without arguments.

sudo sh -c "echo /opt/oracle/instantclient_23_26 > /etc/ld.so.conf.d/oracle-instantclient.conf"
sudo ldconfig

// app.js
oracledb.initOracleClient();

3Verify

ldconfig lists libclntsh and the app connects in Thick mode.

ldconfig -p | grep clntsh

Confirmed by node-oracledb.readthedocs.io

Did this fix it?

Cause 3 of 5

libaio is missing

1Check

Instant Client on Linux needs the libaio package. On some distributions the package is named libaio1 or libaio1t64.

ldconfig -p | grep libaio

2Fix

Install the package. If the new libaio1t64 package is installed and libaio.so.1 is still not found, add a symbolic link from libaio.so.1t64 to libaio.so.1.

sudo apt install -y libaio1t64
# only if libaio.so.1 is still missing
sudo ln -s /usr/lib/x86_64-linux-gnu/libaio.so.1t64 /usr/lib/x86_64-linux-gnu/libaio.so.1
sudo ldconfig

3Verify

ldconfig lists libaio.so.1 and DPI-1047 is gone.

ldconfig -p | grep libaio

Confirmed by node-oracledb.readthedocs.io

Did this fix it?

Cause 4 of 5

Node.js and the client library differ in bitness

1Check

Node.js and the Oracle Client libraries must both be 64-bit or both 32-bit. Compare the two.

node -p 'process.arch'
file /opt/oracle/instantclient_23_26/libclntsh.so*

2Fix

Download the Instant Client package whose architecture matches your Node.js build.

# download the Basic or Basic Light package for the architecture printed above

3Verify

file and process.arch agree, and the app connects.

DPI_DEBUG_LEVEL=64 node app.js

Confirmed by node-oracledb.readthedocs.io

Did this fix it?

Cause 5 of 5

The Oracle Client library is too old for Thick mode

1Check

The troubleshooting guide says Thick mode needs Oracle Client 19 or later. Look at the version in the library file name.

ls /opt/oracle/*/libclntsh.so*

2Fix

Install a current Instant Client (19 or later), update the ldconfig file to its folder, and run ldconfig.

sudo sh -c "echo /opt/oracle/instantclient_23_26 > /etc/ld.so.conf.d/oracle-instantclient.conf"
sudo ldconfig

3Verify

The app starts in Thick mode without DPI-1072 or DPI-1047.

node app.js

Confirmed by node-oracledb.readthedocs.io

Did this fix it?

How do I stop it coming back?

  • Stay on Thin mode unless a feature needs Thick mode, so there is no client library to maintain.
  • Install Instant Client under /opt or /usr/local, since libraries in user folders can be blocked by the operating system.
  • Register the folder with ldconfig in your image or provisioning script, instead of relying on an environment variable.
  • Check that the Node.js process can read the client files.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.