Skip to content

Latest commit

 

History

History
369 lines (248 loc) · 12.8 KB

troubleshooting.rst

File metadata and controls

369 lines (248 loc) · 12.8 KB

Troubleshooting Errors

Use the troubleshooting information documented in this section to address errors that may appear while :ref:`installing <instllntroubleshooting>` or :ref:`using <runtimetroubleshooting>` python-oracledb in Thin or Thick mode.

Installation Errors

You may encounter issues while installing python-oracledb. Review the python-oracledb :ref:`instreq`. 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.

"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

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

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

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

"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 :ref:`installgh`.

Warning Messages

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

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.

Error Messages

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

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.

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 :ref:`features available in python-oracledb's default Thin mode <featuresummary>`. If Thin mode suits your requirements, then remove the calls in your application to :meth:`oracledb.init_oracle_client()` since this loads the Oracle Client library to :ref:`enable Thick mode <enablingthick>`.

  • On Windows and macOS, pass the lib_dir library directory parameter in your :meth:`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:

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

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 :ref:`instreq`. You can either:

DPY Error Messages

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

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:

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:

  • :ref:`Enable Thick mode <enablingthick>` 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

      .. seealso::

   `Finding and Resetting User Passwords That Use the 10G Password
   Version <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=
   GUID-D7B09DFE-F55D-449A-8F8A-174D89936304>`__ for more information.

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:

.. seealso::

    `Oracle Database Security Guide <https://www.oracle.com/pls/topic/lookup?
    ctx=dblatest&id=DBSEG>`__ for more information about Oracle Data Network
    Encryption and Integrity, and for information about configuring TLS
    network encryption.