26. Troubleshooting Errors — python-oracledb 3.2.0b1 documentation (original) (raw)

Use the troubleshooting information documented in this section to address common errors that may appear while installingor using python-oracledb.

This chapter does not list all possible errors.

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

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

26.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/orhttps_proxy.
• Or try the following command:
  python -m pip install --proxy=http://proxy.example.com:80 oracledb --upgrade

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

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

26.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 onBuilding a python-oracledb package locally.

26.2. Warning Messages

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

26.2.1. Deprecated Python Version 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 versions 3.7 and 3.8.)

Cause: import oracledb gives this warning because you are using a version of Python that is longer maintained by the Python core team.

Action: You can either:

• Upgrade your Python version to 3.9 or later.
• Or you can temporarily suppress the warning by importing thewarnings module and adding a call like warnings.filterwarnings(action='ignore', module="oracledb") before importing oracledb.
• Install an older version of python-oracledb

26.3. Error Messages

While using python-oracledb in Thin or Thick mode, you may encounter errors. Some common DPI, DPY, and ORA 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.

26.3.1. DPI Error Messages

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

Some common DPI error messages are discussed below.

26.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:
  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 thecurrently configured database.
  • If you are not passing a library directory parameter tooracledb.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 toLD_LIBRARY_PATH is to ensure that a file in the /etc/ld.so.conf.ddirectory contains the path to the Instant Client directory, and then runldconfig.

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

26.3.2. DPY Error Messages

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

Some common DPY error messages are discussed below.

26.3.2.1. DPY-3001

Message: DPY-3001: Native Network Encryption and Data Integrity is only supported in python-oracledb thick mode

Action: To verify if NNE or checksumming are 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 or checksumming are enabled, you can resolve this error by either:

• Changing the architecture to use Transport Layer Security (TLS), which is supported in python-oracledb Thin and Thick modes. See Configuring Transport Layer Security Encryption.
• Or enabling python-oracledb Thick mode.

See also

Oracle Database Security Guide for more information about Oracle Data Network Encryption and Integrity, and for information about configuring TLS network encryption.

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

26.3.2.3. 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 parametersec_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 21cso only step 2 is required for this, or subsequent, database versions.

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

26.3.2.4. DPY-3029

Message: DPY-3029: "{name}" includes characters that are not allowed

Cause: Characters were used that are not supported by Oracle Net in the shown connection or configuration parameter or attribute.

Action: Values should be ASCII letters or digits. Allowed special characters are '<>/,.:;-_$+*#&!%?@. Values should not contain enclosing quotes. Also remove trailing commas and trailing backslashes.

26.3.2.5. DPY-4011

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

Cause: If this occurs when using an already opened connection, additional messages may indicate a reason.

If the error occurs when creating a connection or connection pool with python-oracledb 2 or earlier, the common cause is that Oracle Database has Native Network Encryption (NNE) enabled. NNE and Oracle Net checksumming are only supported in python-oracledb Thick mode.

Action: Review if NNE or checksumming are enabled. SeeDPY-3001 for solutions.

If additional messages indicate a reason, follow their guidance.

26.3.3. ORA Error Messages

A common ORA error message is discussed below.

26.3.3.1. ORA-00933

Message: ORA-00933: SQL command not properly ended orORA-00933: unexpected keyword at or near <keyword_value>

Cause: Commonly this error occurs when the SQL statement passed to Oracle Database contains a trailing semicolon.

Action: If your code is like:

cursor.execute("select * from dept;")

Then remove the trailing semi-colon:

cursor.execute("select * from dept")

Note with Oracle Database 23ai this incorrect usage gives the messageORA-03048: SQL reserved word ';' is not syntactically valid following 'select * from dept'.