node-oracledb DPI-1047 and libclntsh.so cannot open shared object file
DPI-1047: Cannot locate an Oracle Client libraryShort 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.
Fix it fast
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.js2Match what you see, then jump to its fix
- 1
The error appears on the call to initOracleClient(), and Instant Client was never installedinitOracleClient() is called but you do not need Thick modeFix - 2
DPI_DEBUG_LEVEL=64 shows the search ending without finding libclntsh.soThe Instant Client folder is not in the system library pathFix - 3
The library is on the path, but loading still fails and libaio.so.1 is not foundlibaio is missingFix - 4
The error says 64-bit library, or the file command shows 32-bit librariesNode.js and the client library differ in bitnessFix - 5
An 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
- 1
What does the error look like?
DPI-1047: Cannot locate an Oracle Client libraryDPI-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.jsConfirmed by node-oracledb.readthedocs.io
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 clntsh2Fix
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 clntshConfirmed by node-oracledb.readthedocs.io
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 libaio2Fix
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 ldconfig3Verify
ldconfig lists libaio.so.1 and DPI-1047 is gone.
ldconfig -p | grep libaioConfirmed by node-oracledb.readthedocs.io
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 above3Verify
file and process.arch agree, and the app connects.
DPI_DEBUG_LEVEL=64 node app.jsConfirmed by node-oracledb.readthedocs.io
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 ldconfig3Verify
The app starts in Thick mode without DPI-1072 or DPI-1047.
node app.jsConfirmed by node-oracledb.readthedocs.io
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
Databases
mongodb-memory-server will not start under Jest or in Docker
NoSystemBinaryFoundError
When mongodb-memory-server fails to start, the real reason is hidden behind a generic message.
4 causes, each with a fixDatabases
Installing the Airflow MySQL provider fails on pkg-config or mysqlclient
Building the mysqlclient wheel fails during the install
The Airflow MySQL provider depends on mysqlclient, which pip compiles against the MySQL C client library.
2 causes, each with a fixDatabases
Compiling a C or C++ program that includes mysql.h fails
undefined reference to `mysql_init'
The compiler only finds mysql.h when the MySQL client development files are installed and their folder is on the include path.
3 causes, each with a fixDatabases
DBeaver cannot run pg_restore: the utility is not found in the client home
Utility 'pg_restore' not found in client home '/usr/lib' (/usr/lib)
DBeaver runs pg_restore from a local PostgreSQL client folder; it does not bundle one.
3 causes, each with a fixDatabases
Django cannot connect to PostgreSQL: connection refused on port 5432, locally or in Docker
Is the server running on that host and accepting TCP/IP connections?
Connection refused means nothing accepted the connection at the host and port Django used.
4 causes, each with a fixDatabases
manage.py test stops with 'permission denied to create database' on PostgreSQL
django.db.utils.ProgrammingError: permission denied to create database
Django creates a separate database called test_ plus your database name, using the DATABASES USER.
2 causes, each with a fix