24. Troubleshooting Errors

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

24.1. Installation Errors

You may encounter issues while installing python-oracledb. Review the python-oracledb Installation Requirements. To understand the problem better, you can display more output by using the -v option with the pip install command. Review your output and logs.

If you need to modify your system version of Python and do not have the necessary access to modify it, then use:

python -m pip install oracledb --upgrade --user

Or you can use the venv module (built into Python 3.x).

This section covers some specific errors or problems that you may run into during python-oracledb installation, and possible solutions to resolve them.

If the installation problem still persists, then try to install python-oracledb using a different method. Google anything that looks like an error. Try some potential solutions.

24.1.1. “Not a supported wheel on this platform” Error

Cause: The python-oracledb installation failed with this error because you may be using an older version of pip.

Action: Upgrade your pip version with the following command:

python -m pip install pip --upgrade --user

24.1.2. Network Connection Error

Cause: The python-oracledb installation failed because of a network connection error.

Action: To resolve this issue:

Check if you need to set the environment variables http_proxy and/or https_proxy.

Or try the following command:

python -m pip install --proxy=http://proxy.example.com:80 oracledb --upgrade

24.1.3. Upgrade to Latest Version Failed Without Any Errors

Cause: The upgrade to the latest python-oracledb version failed without any errors because the old version is still installed.

Action: To reinstall the latest version, try the following command:

python -m pip install oracledb --upgrade --force-reinstall

24.1.4. “No module named pip” Error

Cause: The python-oracledb installation failed with this error because the pip module that is built into Python may sometimes be removed by the OS.

Action: Instead, use the venv module (built into Python 3.x) or virtualenv module.

24.1.5. “fatal error: dpi.h: No such file or directory” Error

Cause: The python-oracledb installation from source code failed because a subdirectory called “odpi” may be missing.

Action: Check if your source installation has a subdirectory called “odpi” containing files. If this is missing, review the section on Install Using GitHub.

24.2. Warning Messages

Some warnings may appear while using python-oracledb in Thick or Thin mode.

24.2.1. Deprecated Python Versions 3.6 and 3.7 Warning

Warning: Python 3.6 is no longer supported by the Python core team. Therefore, support for it is deprecated in python-oracledb and will be removed in a future release. (A similar warning will also be displayed for Python version 3.7.)

Cause: import oracledb gives this warning because you are using deprecated Python versions 3.6 or 3.7 which will be removed in a future release by the Python core team.

Action: You can either:

Upgrade your Python version to 3.8 or later.
Or you can temporarily suppress the warning by importing the warnings module and adding a call like warnings.filterwarnings(action='ignore', module="oracledb") before importing oracledb.

24.3. Error Messages

While using python-oracledb in Thin or Thick mode, you may encounter errors. Some common DPI and DPY errors are detailed in this section with information about the probable cause of the error, and the recommended action which may resolve the error.

If you have multiple versions of Python installed, ensure that you are using the correct python and pip (or python3 and pip3) executables.

24.3.1. DPI Error Messages

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

24.3.1.1. DPI-1047

Message: DPI-1047: Oracle Client library cannot be loaded

Cause: The connection to Oracle Database failed because the Oracle Client library could not be loaded.

Action: Perform the following steps:

Review the features available in python-oracledb’s default Thin mode. If Thin mode suits your requirements, then remove the calls in your application to oracledb.init_oracle_client() since this loads the Oracle Client library to enable Thick mode.
On Windows and macOS, pass the lib_dir library directory parameter in your oracledb.init_oracle_client() call. The parameter should be the location of your Oracle Client libraries. Do not pass this parameter on Linux.
Check if the Python 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 Python 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 Python.
Set the environment variable DPI_DEBUG_LEVEL to 64 and restart python-oracledb. The trace messages will show how and where python-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 you have a full database installation, ensure that this database is the currently configured database.
- If you are not passing a library directory parameter to oracledb.init_oracle_client(), 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.init_oracle_client() 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 and daemons 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.

24.3.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 python-oracledb Thick mode. The Thick mode needs Oracle Client library 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 may be use python-oracledb Thin mode which can be done by removing calls to oracledb.init_oracle_client() from your code.

24.3.2. DPY Error Messages

The python-oracledb Thin mode code and python-oracledb Thick mode code generates error messages with the prefix DPY.

24.3.2.1. DPY-3010

Message: DPY-3010: connections to this database server version are not supported by python-oracledb in thin mode

Cause: The connection to Oracle Database with python-oracledb Thin mode failed because you are using Oracle Database version 11.2 or earlier. Using python-oracledb Thin mode, you can connect directly to Oracle Database 12.1 or later.

Action: You can either:

Enable python-oracledb Thick mode since this mode can connect to Oracle Database 9.2 or later. For Thick mode, you need to install Oracle Client libraries and call oracledb.init_oracle_client() in your code.
Upgrade your Oracle database to python-oracledb Thin mode supported versions 12.1 or later.

24.3.2.2. DPY-3015

Message: DPY-3015: password verifier type 0x939 is not supported by python-oracledb in thin mode

Cause: The connection to Oracle Database with python-oracledb Thin mode failed because your user account was only created with the 10G password verifier. The python-oracledb Thin mode supports password verifiers 11G and later.

Action: You can either:

Enable Thick mode since python-oracledb Thick mode supports password verifiers 10G and later.
Or you can:
1. Ensure that the database initialization parameter sec_case_sensitive_logon is not FALSE. To check the value, connect as SYSDBA in SQL*Plus and run:
```
show parameter sec_case_sensitive_logon
```
Note this parameter has been removed in Oracle Database 21c so only step 2 is required for this, or subsequent, database versions.
1. Regenerate passwords for users who have old password verifiers. You can find such users with the query:
```
select username from dba_users
where (password_versions = '10G ' or password_versions = '10G HTTP ')
and username <> 'ANONYMOUS';
```
  You can reset passwords for these users with commands like:
```
alter user x identified by y
```
  See also
  
  Finding and Resetting User Passwords That Use the 10G Password Version for more information.

24.3.2.3. DPY-4011

Message: DPY-4011: the database or network closed the connection

Cause: The connection failed because the Oracle Database that you are trying to connect to using python-oracledb Thin mode may have Native Network Encryption (NNE) enabled. NNE is only supported in python-oracledb Thick mode.

Action: To verify if NNE is enabled, you can use the following query:

SELECT network_service_banner FROM v$session_connect_info;

If NNE is enabled, then this query prints output that includes the available encryption service, the crypto-checksumming service, and the algorithms in use, such as:

NETWORK_SERVICE_BANNER
-------------------------------------------------------------------------------------
TCP/IP NT Protocol Adapter for Linux: Version 19.0.0.0.0 - Production
Encryption service for Linux: Version 19.0.1.0.0 - Production
AES256 Encryption service adapter for Linux: Version 19.0.1.0.0 - Production
Crypto-checksumming service for Linux: Version 19.0.1.0.0 - Production
SHA256 Crypto-checksumming service adapter for Linux: Version 19.0.1.0.0 - Production

If NNE is not enabled, then the query will only print the available encryption and crypto-checksumming services in the output. For example:

NETWORK_SERVICE_BANNER
-------------------------------------------------------------------------------------
TCP/IP NT Protocol Adapter for Linux: Version 19.0.0.0.0 - Production
Encryption service for Linux: Version 19.0.1.0.0 - Production

If NNE is enabled, you can resolve this error by either:

Changing the architecture to use Transport Layer Security (TLS) which is supported in python-oracledb Thin mode instead of using NNE.
Or enabling python-oracledb Thick mode since NNE is supported in Thick mode.