tnsping with Oracle instant-client?

The instant client

For an application server that connects to Oracle, you probably would not like to install gigabytes of a full Oracle client software? For that, Oracle offers the so-called “Instant Client” you can download for free at oracle.com. It is available for different platforms and in different package formats (rpm, zip, …)

There are different components you can download. Always required is the “basic” or “basic lite” package with the core libraries. Additionally you can install sqlplus, tools (sqlldr, datapump), sdk and the odbc component.

Analyzing connection problems

Analyzing with the “normal” client

If you have issues with the naming resolution, you will probably start with the tnsping utility:

$  tnsping DB01

TNS Ping Utility for Linux: Version 19.0.0.0.0 - Production on 27-OCT-2026 17:25:09

Copyright (c) 1997, 2026, Oracle.  All rights reserved.

Used parameter files:
/u00/app/oracle/network/admin/sqlnet.ora

TNS-03505: Failed to resolve name

It will show you which TNS_ADMIN (the location of the sqlnet.ora and the other *.ora files) is used. It will look in $TNS_ADMIN and if it is not set, in $ORACLE_HOME/network/admin.

And why “Failed to resolve name”? Have a look at the names.directory_path parameter in the sqlnet.ora file, e.g.

NAMES.DIRECTORY_PATH=(LDAP, TNSNAMES)
# default is (tnsnames, ezconnect, ldap)

In this case the alias “DB01” is unknown in LDAP and the tnsnames.ora. For LDAP, check that the ldap.ora is correctly defined and the ldap server running and reachable, otherwise it will be skipped and only the tnsnames.ora is evaluated. See also my Oracle LDAP Timeouts blog.

If the alias exists, but the connection fails, you will get the resolved connect-string you can analyze.

Attempting to contact (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = server01)(PORT = 1521)) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_NAME = TEST.dbi-services.com)))
TNS-12545: Connect failed because target host or object does not exist

Analyzing with the Instant Client

If you are using the instant client, unfortunately there is no tnsping available. How we can debug the connection? The only instantclient binary we have is sqlplus.

First, check if the variable TNS_ADMIN is set. Then, the configuration in this directory is used.

If not, where does it look for?

If you extract the instant client from the .zip file, binaries and libraries are all in the same directory (.rpm is different). To run sqlplus, the libraries of the instantclient have to be in $LD_LIBRARY_PATH, otherwise we get

sqlplus: error while loading shared libraries: libsqlplus.so: cannot open shared object file: No such file or directory

To see where sqlplus will look for the network configuration (*.ora) we can use the strace utility of Linux.

$ strace sqlplus x/y@DB01  2>&1 |grep sqlnet.ora
access("/u00/app/oracle/product/instantclient/instantclient_21_7/network/admin/sqlnet.ora", F_OK) = -1 ENOENT (No such file or directory)

Is this the path from the binary, or the path from LD_LIBTRARY_PATH? To find it out, I will write the path for the libraries relative.

export PATH=$PATH:/u00/app/oracle/product/instantclient/instantclient_21_7
cd /u00/app/oracle/product/instantclient/instantclient_21_7
LD_LIBRARY_PATH=../instantclient_21_7 strace sqlplus x/y@DB01  2>&1 |grep sqlnet.ora

access("../instantclient_21_7/network/admin/sqlnet.ora", F_OK) = -1 ENOENT (No such file or directory)
access("../instantclient_21_7/network/admin/sqlnet.ora", F_OK) = -1 ENOENT (No such file or directory)
access("/home/oracle/.sqlnet.ora", F_OK) = -1 ENOENT (No such file or directory)

As you can see, it looks for the configuration below the library location in network/admin. And that is different from an sqlplus in a “normal” ORACLE_HOME, where it looks for $ORACLE_HOME/network/admin!

Now you can check the *.ora files in this directory and analyze why the name can’t be resolved.

If the name is resolved, but the connect fails, you have to get the resolved connect string. Note the order of names.directory_path!

If LDAP is one of the naming methods, it is a little bit more complicated. You can use the ldapsearch binary. Depending on the version from openldap or oracle, the syntax is slightly different:

# openldap 
/usr/bin/ldapsearch -o ldif-wrap=no -h localhost -p 389 -D '' \
  -b "cn=DB1970,cn=OracleContext,dc=dbi-services,dc=com" \
  -s sub "objectclass=orclNetService"

# oracle
 ldapsearch  -x -LLL -h localhost -p 389 \
  -b "cn=DB1970,cn=OracleContext,dc=dbi-services,dc=com" \
  -s sub "objectclass=orclNetService"

cn=DB1970,cn=OracleContext,dc=dbi-services,dc=com
objectClass=top
objectClass=orclNetService
cn=DB1970
orclNetDescString=(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=server01)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=DB1970A.dbi-services.com)))

the value of orclNetDescString is the connect string sqlplus uses.

In case of the tnsnames.ora, it is easy: search in the file for an alias “DB01”.

Instant Client on Windows?

Same but differnt 😉 It also evaluates the TNS_ADMIN variable and the network\admin directory below the instant client directory with the *.dll; But additionally, it also evaluates the *.ora files in the current directory.