Home > Oracle, RDBMS > Resolving Oracle networking problems – ORA-12154 and TNS-03505 errors.

Resolving Oracle networking problems – ORA-12154 and TNS-03505 errors.

The original version of the below article was created by Ed Stevens and could be find here.

Continuing the discussion of resolving Oracle networking problems, I’d like to focus on one particular error: ORA-12154. For this discussion and demonstration we will use Oracle’s sqlplus command processor as our client, but the principles apply to any client program that uses sqlnet to connect to the database.

There are actually several mechanisms for connecting to an Oracle database, but by far the most common is via the Oracle Call Interface (OCI), passing the connect request via Oracle’s Transparent Network Substrate (TNS), commonly referred to as “sqlnet”.

When I got this error for the first time (and a couple times more), I’ve started to check everything that can go wrong anywhere along the network stack. And yet, ORA-12154 means one thing, and one thing only: “the client side of sqlnet could not find the specified connect identifier”. Period. And the official description of the error, returned by the Oracle utility oerr spells it out:

[oracle@orclsvr ~]$ oerr ora 12154
12154, 00000, "TNS:could not resolve the connect identifier specified"
// *Cause:  A connection to a database or other service was requested using
// a connect identifier, and the connect identifier specified could not
// be resolved into a connect descriptor using one of the naming methods
// configured. For example, if the type of connect identifier used was a
// net service name then the net service name could not be found in a
// naming method repository, or the repository could not be
// located or reached.

Or more succinctly: “A connection… was requested using a connect identifier (which) could not be resolved into a connect descriptor”. So what is the connect identifier?

Let’s take the classic, textbook example of a simple client connection request:

c:\> sqlplus scott/tiger@orcl

By the rules Oracle uses to parse the command line, the “@” symbol is used to mark the beginning of the connect identifier. So in this example, the connect identifier is “orcl”, and an ORA-12154 means an entry for “orcl” could not be resolved to a “connect descriptor” – the IP address, port number, and service name necessary to properly route the request across the network to the Oracle listener. There are several methods available to make this name resolution, but by far the most common is the use of “local naming” – the tnsnames.ora file.
This file serves no other purpose, so you should have it fixed firmly in your mind that it is used only by the client process. The only reason this file exists on the database server is because the server can also run client processes.

With this preliminary information out of the way, let’s dig in and see how many ways we can create (and conversely, fix) an ORA-12154. Let’s first look at a good configuration, then we’ll start taking it apart. My database is running on an Windows 2008R2 server, while my client (Oracle 32bit) is running on my laptop, under Windows 7 Pro 64bit. My tnsnames.ora looks like this:

# tnsnames.ora Network Configuration File: c:\oracle\11.2.0\CLIENT\network\admin\tnsnames.ora
# Generated by Oracle configuration tools.
myorcl =
      (ADDRESS = (PROTOCOL = TCP)(HOST = orclsvr)(PORT = 1521))
      (SERVICE_NAME = orcl)

Make a connection to the database, just to show that everything is in order.

Right out of the textbook! So what could go wrong, to generate an ORA-12154?

Wrong naming method.
The first thing sqlnet has to do is determine what naming method is being used – exactly how it is to resolve the connect identifier to an IP address, port, and service name. To do this, it looks in the file ‘sqlnet.ora’ (on the client machine, of course!) for the parameter NAMES.DIRECTORY_PATH. If we intend to use local naming, we must set this parameter appropriately:


Note: the string ‘TNSNAMES’ as a value for this parameter is not the name of the file. It is the name of the method to be used for name resolution. The name of the file used for this method is always tnsnames.ora.

Let’s set it to some other value (albeit a valid one)…

# sqlnet.ora Network Configuration File: c:\oracle\11.2.0\CLIENT\network\admin\sqlnet.ora

… and observe the behavior:

In this example, we told sqlnet to use LDAP naming services to resolve the connect identifier, but LDAP is not available in my test environment, thus it was not able to resolve “myorcl”. If you want to use local naming, you must specify such in the NAMES.DIRECTORY_PATH parameter in the client’s sqlnet.ora file. Let’s fix the problem, then move on:

# sqlnet.ora Network Configuration File: c:\oracle\11.2.0\CLIENT\network\admin\sqlnet.ora

Can’t locate tnsames.ora
The entire subject of locating tnsnames.ora was covered here. For now, I will create the simplest means of not being able to locate the file – I’ll rename it to something else:

C:\>cd C:\oracle\11.2.0\CLIENT\NETWORK\ADMIN

C:\oracle\11.2.0\CLIENT\NETWORK\ADMIN>ren tnsnames.ora tnsnames.sav

C:\oracle\11.2.0\CLIENT\NETWORK\ADMIN>dir tnsnames.ora
	 Volume in drive C is SYSTEM.
	 Volume Serial Number is 08AF-B8C9

	 Directory of C:\oracle\11.2.0\CLIENT\NETWORK\ADMIN

         File Not Found


and observe the result:

Of course, we fix it by providing a (valid) tnsnames.ora file:

C:\oracle\11.2.0\CLIENT\NETWORK\ADMIN>ren tnsnames.sav tnsnames.ora

Can’t find connect descriptor in tnsnames.ora
We’ve told sqlnet to use tnsnames, and we’ve made sure sqlnet can find tnsnames.ora. But what if the connect identifier we provide cannot be found in the tnsnames.ora? And more importantly, what can cause it to not be found?
Of course, the simplest reason would be that we just gave it the wrong string. In our example file (shown above), we had a single entry, with the connect identifier of ‘myorcl’. If we provide a different connect identifier it will, of course fail – again with ORA-12154:

But there is another factor that comes into play at this point. There is an optional parameter that can be set in sqlnet.ora that we have not yet discussed. Before looking in tnsnames.ora, sqlnet will check to see if the parameter NAMES.DEFAULT_DOMAIN has been set. If it has, it’s value will be appended to the connect descriptor supplied by the user – before searching tnsames.ora for the result. Let’s add that parameter to our existing sqlnet.ora:

# sqlnet.ora Network Configuration File: c:\oracle\11.2.0\CLIENT\network\admin\sqlnet.ora

and observe the result:

There are two ways to fix this error. Obviously, we can revert back to our previous configuration by removing the NAMES.DEFAULT_DOMAIN parameter from sqlnet.ora. The other would be to add the domain name to the entry in tnsnames.ora:

# tnsnames.ora Network Configuration File: c:\oracle\11.2.0\CLIENT\network\admin\tnsnames.ora
# Generated by Oracle configuration tools.
myorcl.world.com =
      (ADDRESS = (PROTOCOL = TCP)(HOST = orclsvr)(PORT = 1521))
      (SERVICE_NAME = orcl)

That pretty well covers every means of creating an ORA-12154 when using local naming. What about the TNS-03505 error? Actually, TNS-3505 is exactly the same error as ORA-12154, with all the same causes and resolutions. The only difference I’ve been able to discover is that TNS-03505 is produced when using the ‘tnsping’ utility. Why Oracle chose to code tnsping this way I don’t know, and I’ve been unable to find definitive documentation on this difference but my own testing bears it out.
Using sqlplus:

and using tnsping:

There is one often overlooked ‘gotcha’ in all this. Remember that when sqlnet is parsing out the connect string, it uses the ‘@’ sign as a meta-character to mark the beginning of the connect descriptor. So if we have this:

c:\>sqlplus scott/tiger@myorcl

everything is just fine. But suppose there is an ‘@’ sign someplace unexpected. What happens if someone constructs a complex password that includes it?

c:\>sqlplus scott/P@ssW0rd@myorcl

In this case, sqlnet will take the ‘P’ as the password, and take ‘ssW0rd@myorcl’ as the connect descriptor. By now, you can guess the result.

There is one overriding factor here that should be obvious from the very description of the error, regardless of the naming method used: ORA-12154 is a client side problem. It has absolutely nothing to do with anything on the server. It has nothing to do with the listener; it has nothing to do with the database. If you are faced with a ORA-12154, you can monkey around with your database and/or listener “until the cows come home” and you will not solve your problem.

  1. Sandeep
    2013-07-09 at 17:03

    Best description of Ora-12154, I have come across after scanning the net for full 2 days. Great job and Thanks a lot.

  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: