27.3.1.1.DPI-1047

Message:DPI-1047:OracleClientlibrarycannotbeloaded

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

Action: Perform the following steps:

• Review thefeatures available in python-oracledb’s default Thin mode. If Thin mode suits your requirements, then remove thecalls in your application tooracledb.init_oracle_client() sincethis loads the Oracle Client library toenable Thick mode.

• On Windows and macOS, pass thelib_dir library directory parameterin youroracledb.init_oracle_client() call. The parametershould be the location of your Oracle Client libraries. Do not passthis parameter on Linux.

• Check if the Python process has permission to open the Oracle Clientlibraries. OS restrictions may prevent the opening of libraries installedin unsafe paths, such as from a user directory. On Linux you may need toinstall the Oracle Client libraries under a directory like/opt or/usr/local.

• Check if Python and your Oracle Client libraries are both 64-bit orboth 32-bit. TheDPI-1047 message will tell you whether the 64-bitor 32-bit Oracle Client is needed for your Python.

• If you are using Oracle Instant Client libraries (and not using a fullOracle Database installation or a full Oracle Instant Client installation(such as installed by Oracle’s GUI installer)), check whether theORACLE_HOME environment variable is set. If it is, unset this variable.

• Set the environment variableDPI_DEBUG_LEVEL to 64 and restartpython-oracledb. The trace messages will show how and wherepython-oracledb is looking for the Oracle Client libraries.

  At a Windows command prompt, this could be done with:

  setDPI_DEBUG_LEVEL=64

  On Linux and macOS, you might use:

  exportDPI_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 promptand usesetPATH to check if the environment variable has the correctOracle Client listed before any other Oracle directories.

  • Use theDIR command to verify thatOCI.DLL exists in the directorypassed tooracledb.init_oracle_client() or set inPATH.

  • Check if the correctWindows Redistributables have been installed.

• On Linux:

  • Check if theLD_LIBRARY_PATH environment variable contains the OracleClient library directory. Some environments such as web servers anddaemons 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.

27.3.1.2.DPI-1072

Message:DPI-1072:theOracleClientlibraryversionisunsupported

Cause: The connection to Oracle Database failed because the Oracle Clientlibrary version used is not supported by python-oracledb Thick mode. The Thickmode needs Oracle Client library 11.2 or later.

Action: Review theInstallation Requirements. You can either:

• Follow the steps documented inDPI-1047 which may help.

• Or may be use python-oracledb Thin mode which can be done by removing callstooracledb.init_oracle_client() from your code.

27.3.2.1.DPY-3001

Message:DPY-3001:NativeNetworkEncryptionandDataIntegrityisonlysupportedinpython-oracledbthickmode

Action: To verify if NNE or checksumming are enabled, you can use thefollowing query:

SELECT network_service_banner FROM v$session_connect_info;

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

NETWORK_SERVICE_BANNER-------------------------------------------------------------------------------------TCP/IPNTProtocolAdapterforLinux:Version19.0.0.0.0-ProductionEncryptionserviceforLinux:Version19.0.1.0.0-ProductionAES256EncryptionserviceadapterforLinux:Version19.0.1.0.0-ProductionCrypto-checksummingserviceforLinux:Version19.0.1.0.0-ProductionSHA256Crypto-checksummingserviceadapterforLinux:Version19.0.1.0.0-Production

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

NETWORK_SERVICE_BANNER-------------------------------------------------------------------------------------TCP/IPNTProtocolAdapterforLinux:Version19.0.0.0.0-ProductionEncryptionserviceforLinux:Version19.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 issupported in python-oracledb Thin and Thick modes. SeeConfiguringTransport Layer Security Encryption.

• Orenabling python-oracledb Thick mode.

27.3.2.2.DPY-3010

Message:DPY-3010:connectionstothisdatabaseserverversionarenotsupportedbypython-oracledbinthinmode

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

Action: You can either:

• Enable python-oracledb Thick mode since this mode canconnect to Oracle Database 9.2 or later. For Thick mode, you need to installOracle Client libraries and calloracledb.init_oracle_client() inyour code.

• Upgrade Oracle Database to 12.1, or later, if you want to use python-oracledbThin mode.

27.3.2.3.DPY-3015

Message:DPY-3015:passwordverifiertype0x939isnotsupportedbypython-oracledbinthinmode

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

Action: You can either:

• Enable Thick mode since python-oracledb Thick modesupports password verifiers 10G and later.

• Or you can:

  1. Ensure that the database initialization parametersec_case_sensitive_logon is notFALSE. To check the value, connectas SYSDBA in SQL*Plus and run:

     showparametersec_case_sensitive_logon

  Note this parameter wasremoved 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 canfind such users with the query:

     selectusernamefromdba_userswhere(password_versions='10G 'orpassword_versions='10G HTTP ')andusername<>'ANONYMOUS';

     You can reset passwords for these users with commands like:

     alteruserxidentifiedbyy;

     See also

     Finding and Resetting User Passwords That Use the 10G PasswordVersion for more information.

27.3.2.4.DPY-3029

Message:DPY-3029:"{name}"includescharactersthatarenotallowed

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

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

27.3.2.5.DPY-4011

Message:DPY-4011:thedatabaseornetworkclosedtheconnection

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

If the error occurs when creating a connection or connection pool withpython-oracledb 2 or earlier, the common cause is that Oracle Database hasNative Network Encryption (NNE) enabled. NNE and Oracle Net checksumming areonly 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.

27.3.2.6.DPY-4027

Message:DPY-4027:noconfigurationdirectoryspecified

Cause: Theconnection string specified in your connectionor pool creationdsn parameter was interpreted by python-oracledb to be aTNS Alias which it needed to look up in atnsnames.ora file. However, python-oracledb did not knowwhere to find that file.

Action: You need to either tell python-oracledb where to find thetnsnames.ora file, or use a different connection stringsyntax. Perform one of the following:

• Use the equivalentEasy Connect syntax orConnectDescriptor:

  c=oracledb.connect(user="hr",password=userpw,dsn="localhost:1521/orclpdb")

  Or:

  c=oracledb.connect(user="hr",password=userpw,dsn="(DESCRIPTION=(ADDRESS=(...))")

• Review thedefaults.config_dir documentation for the heuristics usedby python-oracledb to automatically locatetnsnames.ora. Ensure that your file is in an expected location, that thefile is readable by Python, and that any necessary environment variables suchasTNS_ADMIN are accessible by the Python process.

• If you have problems with the heuristics, then you can explicitly specify thelocation oftnsnames.ora. For example, if the file is at/opt/myconfigdir/tnsnames.ora, then:

  • In python-oracledb’s default Thin mode, or whendefaults.thick_mode_dsn_passthrough isFalse, you can use:

    c=oracledb.connect(user="hr",password=userpw,dsn="MYDB",config_dir="/opt/myconfigdir")

  • In python-oracledb’sThick mode (which is the modewhen your application callsoracledb.init_oracle_client()), then youcan use:

    oracledb.init_oracle_client(config_dir="/opt/myconfigdir")c=oracledb.connect(user="hr",password=userpw,dsn="MYDB")

27.3.3.1.ORA-00933

Message:ORA-00933:SQLcommandnotproperlyended orORA-00933:unexpectedkeywordatornear<keyword_value>

Cause: Commonly this error occurs when the SQL statement passed to OracleDatabase 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:SQLreservedword';'isnotsyntacticallyvalidfollowing'select*fromdept'.

27.3.3.2.ORA-28009

Message:ORA-28009:connectionasSYSshouldbeasSYSDBAorSYSOPER

Cause: Commonly this error occurs when you try to create a connection poolusingoracledb.AUTH_MODE_SYSDBA in python-oracledb Thick mode.

Action: Use astandalone connection.Alternatively, use python-oracledb Thin mode by removing all calls tooracledb.init_oracle_client().